001 package org.esupportail.cas.server.util;
002
003 import org.dom4j.Element;
004 import org.esupportail.cas.server.util.log.Debug;
005
006 /**
007 * This class implements a basic handler, without any property.
008 * This abstract class is inherited by any handler.
009 *
010 * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
011 */
012 public abstract class BasicHandler extends Debug {
013
014 /**
015 * The value return by authenticate() when the authentication
016 * was successfull.
017 */
018 public static final int SUCCEEDED = 1;
019 /**
020 * The value return by authenticate() when the authentication
021 * failed but the next handler should be tried.
022 */
023 protected static final int FAILED_CONTINUE = 2;
024 /**
025 * The value return by authenticate() when the authentication
026 * failed and the authentication process should stop.
027 */
028 public static final int FAILED_STOP = 3;
029
030 /**
031 * The XML element that represents the configuration of the handler
032 * in the configuration file.
033 */
034 private Element configElement;
035
036
037 /**
038 * Retrieve the XML element the represents the configuration of the handler
039 * in the configuration file.
040 *
041 * @return an XML element.
042 */
043 protected final Element getConfigElement() {
044 return configElement;
045 }
046
047 /**
048 * Constructor.
049 *
050 * @param handlerElement the XML element that declares the handler
051 * in the configuration file
052 * @param configDebug debugging mode of the global configuration
053 */
054 protected BasicHandler(
055 final Element handlerElement,
056 final Boolean configDebug) {
057 super(elementDebugValue(handlerElement, configDebug.booleanValue()));
058 traceBegin();
059 configElement = handlerElement.element("config");
060 traceEnd();
061 }
062
063 /**
064 * Check the "config" XML element if needed.
065 *
066 * @param configElementNeeded true if a config element is needed
067 * @throws Exception Exception
068 */
069 protected final void checkConfigElement(final boolean configElementNeeded) throws Exception {
070 traceBegin();
071 if (configElementNeeded && (getConfigElement() == null)) {
072 traceThrow(new MisconfiguredHandlerException(
073 "A \"config\" element is needed by \""
074 + getClass().getName()
075 + "\" handlers."));
076 }
077 traceEnd();
078 }
079
080 /**
081 * Tries to Authenticate a user by accessing all the servers..
082 *
083 * @param username the username to authenticate
084 * @param password the corresponding password
085 *
086 * @return SUCCEDED on success, FAILED_CONTINUE or FAILED_STOP otherwise.
087 */
088 public abstract int authenticate(
089 final String username,
090 final String password);
091
092 /**
093 * Retrieve the content of a config sub-element.
094 *
095 * @param elementName the name of the XML element to look for
096 * @param needed false if the element can be absent or empty, true otherwise
097 * @return a String
098 * @throws Exception Exception
099 */
100 protected final String getConfigSubElementContent(
101 final String elementName,
102 final boolean needed) throws Exception {
103 Element element = getConfigElement().element(elementName);
104 String str;
105 if (element == null) {
106 str = "";
107 } else {
108 str = element.getTextTrim();
109 }
110 if (needed && str.equals("")) {
111 traceThrow(new MisconfiguredHandlerException(
112 "A non empty nested \"" + elementName + "\" element is needed to configure \""
113 + getClass().getName()
114 + "\" handlers."
115 ));
116 }
117 return str;
118 }
119
120 /**
121 * Tell if a config sub-element is present.
122 *
123 * @param elementName the name of the XML element to look for
124 * @return true if the element is present, false otherwise
125 * @throws Exception Exception
126 */
127 protected final boolean hasConfigSubElement(
128 final String elementName) throws Exception {
129 Element element = getConfigElement().element(elementName);
130 return (element != null);
131 }
132
133 }
134