001: /*
002: * $Id: AbstractCAPICallRequest.java,v 1.40 2007/08/15 13:53:56 agoubard Exp $
003: *
004: * Copyright 2003-2007 Orange Nederland Breedband B.V.
005: * See the COPYRIGHT file for redistribution and use restrictions.
006: */
007: package org.xins.client;
008:
009: import java.io.Serializable;
010: import java.util.HashMap;
011: import java.util.Iterator;
012: import java.util.Map;
013:
014: import org.xins.common.MandatoryArgumentChecker;
015:
016: import org.xins.common.xml.Element;
017: import org.xins.common.xml.ElementBuilder;
018:
019: /**
020: * Base class for generated CAPI function request classes.
021: *
022: * <p>This class should not be subclassed manually. It is only intended to be
023: * subclassed by classes generated by XINS.
024: *
025: * @version $Revision: 1.40 $ $Date: 2007/08/15 13:53:56 $
026: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
027: *
028: * @since XINS 1.2.0
029: */
030: public abstract class AbstractCAPICallRequest implements Serializable {
031:
032: /**
033: * The name the function to call, never <code>null</code>.
034: */
035: private final String _functionName;
036:
037: /**
038: * The call configuration. Initially <code>null</code>.
039: */
040: private XINSCallConfig _callConfig;
041:
042: /**
043: * Mapping from parameter names to either their associated string values or
044: * to an exception if the conversion to a string failed. This field is
045: * lazily initialized and initially <code>null</code>.
046: */
047: private Map _parameterValues;
048:
049: /**
050: * The data section of the function if any, can be <code>null</code>.
051: */
052: private Element _dataSection;
053:
054: /**
055: * The data element builder, can be <code>null</code>.
056: */
057: private ElementBuilder _dataElementBuilder;
058:
059: /**
060: * Creates a new <code>AbstractCAPICallRequest</code>.
061: *
062: * @param functionName
063: * the name of the function used with this request.
064: *
065: * @throws IllegalArgumentException
066: * if <code>functionName == null</code>.
067: */
068: protected AbstractCAPICallRequest(String functionName)
069: throws IllegalArgumentException {
070: MandatoryArgumentChecker.check("functionName", functionName);
071: _functionName = functionName;
072: }
073:
074: /**
075: * Sets the specified parameter to the specified value.
076: *
077: * @param name
078: * the name of the parameter to set, cannot be <code>null</code>.
079: *
080: * @param value
081: * the character string representation of the value of the parameter,
082: * can be <code>null</code>.
083: *
084: * @throws IllegalArgumentException
085: * if <code>name == null</code>.
086: */
087: protected final void parameterValue(String name, String value)
088: throws IllegalArgumentException {
089:
090: // Check preconditions
091: MandatoryArgumentChecker.check("name", name);
092:
093: // If there is no value, then remove the entry from the map
094: if (value == null) {
095: if (_parameterValues != null) {
096: _parameterValues.remove(name);
097: }
098:
099: // Otherwise just store
100: } else {
101:
102: if (_parameterValues == null) {
103: _parameterValues = new HashMap();
104: }
105: _parameterValues.put(name, value);
106: }
107: }
108:
109: /**
110: * Returns an appropriate <code>XINSCallRequest</code> object.
111: *
112: * @return
113: * a {@link XINSCallRequest}, never <code>null</code>.
114: */
115: final XINSCallRequest xinsCallRequest() {
116:
117: // Construct a XINSCallRequest object
118: XINSCallRequest request = new XINSCallRequest(_functionName);
119:
120: // Set all parameters on the request, if any
121: if (_parameterValues != null && _parameterValues.size() > 0) {
122:
123: // Loop over all parameters in the map containing the types
124: Iterator iterator = _parameterValues.keySet().iterator();
125: while (iterator.hasNext()) {
126:
127: // Determine parameter name, type and value
128: String name = (String) iterator.next();
129: String value = (String) _parameterValues.get(name);
130:
131: // Set the parameter on the request
132: request.setParameter(name, value);
133: }
134: }
135:
136: Element dataSection = getDataElement();
137: if (dataSection != null) {
138: request.setDataSection(dataSection);
139: }
140:
141: if (_callConfig != null) {
142: request.setXINSCallConfig(_callConfig);
143: }
144:
145: return request;
146: }
147:
148: /**
149: * Assigns the specified call configuration to this request.
150: *
151: * @param config
152: * the call configuration to apply when executing this request, or
153: * <code>null</code> if no specific call configuration should be
154: * associated with this request.
155: */
156: public final void configure(XINSCallConfig config) {
157: _callConfig = config;
158: }
159:
160: /**
161: * Retrieves the call configuration currently associated with this request.
162: *
163: * @return
164: * the call configuration currently associated with this request, which
165: * will be applied when executing this request, or <code>null</code> if
166: * no specific call configuration is associated with this request.
167: */
168: public final XINSCallConfig configuration() {
169: return _callConfig;
170: }
171:
172: /**
173: * Gets the value of a parameter or <code>null</code> if this parameter
174: * is not set.
175: *
176: * @param parameterName
177: * The name of the parameter, can be <code>null</code>.
178: *
179: * @return
180: * The value of a parameter or <code>null</code> if this parameter
181: * is not set.
182: */
183: protected final String getParameter(String parameterName) {
184: if (_parameterValues == null) {
185: return null;
186: } else {
187: return (String) _parameterValues.get(parameterName);
188: }
189: }
190:
191: /**
192: * Sets the data section.
193: * If the value is <code>null</code> any previous data section set is removed.
194: * If a previous value was entered, the value will be overridden by this new
195: * value.
196: *
197: * @param dataSection
198: * The data section.
199: */
200: protected final void putDataSection(Element dataSection) {
201: _dataSection = dataSection;
202: _dataElementBuilder = null;
203: }
204:
205: /**
206: * Gets the name of the function to call.
207: *
208: * @return
209: * The name of the function to call, never <code>null</code>.
210: *
211: * @since XINS 1.4.0
212: */
213: public final String functionName() {
214: return _functionName;
215: }
216:
217: /**
218: * Add a new Element to the data element.
219: * Any previous value was entered with the method {@link #putDataSection},
220: * will be removed.
221: *
222: * @param element
223: * the new element to add to the result, cannot be <code>null</code>.
224: *
225: * @since XINS 1.3.0
226: */
227: protected void add(Element element) {
228: if (_dataElementBuilder == null) {
229: _dataElementBuilder = new ElementBuilder("data");
230: _dataSection = null;
231: }
232: _dataElementBuilder.addChild(element);
233: }
234:
235: /**
236: * Gets the data section.
237: *
238: * @return
239: * The data section or <code>null</code> if there is no data section.
240: */
241: protected Element getDataElement() {
242: if (_dataElementBuilder != null) {
243: return _dataElementBuilder.createElement();
244: }
245: return _dataSection;
246: }
247:
248: /**
249: * Validates whether this request is considered acceptable. If any
250: * constraints are violated, then an {@link UnacceptableRequestException}
251: * is returned.
252: *
253: * <p>This method is called automatically when this request is executed, so
254: * it typically does not need to be called manually in advance.
255: *
256: * @return
257: * an {@link UnacceptableRequestException} instance if this request is
258: * considered unacceptable, otherwise <code>null</code>.
259: */
260: public abstract UnacceptableRequestException checkParameters();
261:
262: public int hashCode() {
263: int hashCode = _functionName.hashCode();
264: if (_parameterValues != null) {
265: hashCode += _parameterValues.hashCode();
266: }
267: Element dataElement = getDataElement();
268: if (dataElement != null) {
269: hashCode += dataElement.hashCode();
270: }
271: return hashCode;
272: }
273:
274: public boolean equals(Object obj) {
275: if (obj == null || !obj.getClass().isInstance(this )) {
276: return false;
277: }
278: AbstractCAPICallRequest otherRequest = (AbstractCAPICallRequest) obj;
279: if ((_parameterValues != null && !_parameterValues
280: .equals(otherRequest._parameterValues))
281: || (_parameterValues == null && otherRequest._parameterValues != null)) {
282: return false;
283: }
284: Element dataElement = getDataElement();
285: Element otherDataElement = otherRequest.getDataElement();
286: if ((dataElement != null && !dataElement
287: .equals(otherDataElement))
288: || (dataElement == null && otherDataElement != null)) {
289: return false;
290: }
291: return true;
292: }
293: }
|