001: /*
002: * $Id: FunctionResult.java,v 1.43 2007/09/18 08:45:05 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.server;
008:
009: import org.xins.common.MandatoryArgumentChecker;
010: import org.xins.common.collections.BasicPropertyReader;
011: import org.xins.common.collections.PropertyReader;
012: import org.xins.common.collections.PropertyReaderUtils;
013: import org.xins.common.xml.Element;
014: import org.xins.common.xml.ElementBuilder;
015:
016: /**
017: * Result from a function call. Defines an error code, parameters and output
018: * data section. All are optional.
019: *
020: * @version $Revision: 1.43 $ $Date: 2007/09/18 08:45:05 $
021: * @author <a href="mailto:anthony.goubard@japplis.com">Anthony Goubard</a>
022: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
023: *
024: * @since XINS 1.0.0
025: *
026: * @see FunctionRequest
027: */
028: public class FunctionResult {
029:
030: /**
031: * The result code. This field is <code>null</code> if no code was
032: * returned.
033: */
034: private final String _code;
035:
036: /**
037: * The parameters and their values. This field is never <code>null</code>.
038: */
039: private final BasicPropertyReader _parameters;
040:
041: /**
042: * The data element builder. This field is lazily initialized, it is
043: * <code>null</code> if there is no data element.
044: */
045: private ElementBuilder _dataElementBuilder;
046:
047: /**
048: * Creates a new successful <code>FunctionResult</code> instance with no
049: * parameters.
050: */
051: public FunctionResult() {
052: this (null, null);
053: }
054:
055: /**
056: * Creates a new <code>FunctionResult</code> instance with no parameters.
057: *
058: * @param code
059: * the error code, can be <code>null</code> if the result is successful.
060: */
061: public FunctionResult(String code) {
062: this (code, null);
063: }
064:
065: /**
066: * Creates a new <code>FunctionResult</code> instance with a specified set
067: * of parameters.
068: *
069: * @param code
070: * the error code, can be <code>null</code> if the result is successful.
071: *
072: * @param parameters
073: * the parameters for the result, can be <code>null</code> if there are
074: * no parameters.
075: */
076: public FunctionResult(String code, BasicPropertyReader parameters) {
077: _code = code;
078: if (parameters == null) {
079: _parameters = new BasicPropertyReader();
080: } else {
081: _parameters = parameters;
082: }
083: }
084:
085: /**
086: * Returns the result code.
087: *
088: * @return
089: * the result code or <code>null</code> if no code was returned.
090: */
091: public String getErrorCode() {
092: return _code;
093: }
094:
095: /**
096: * Checks that the output parameters are set as specified. If a parameter
097: * is missing or if the value for it is invalid, then an
098: * <code>InvalidResponseResult</code> is returned. Otherwise the parameters
099: * are considered valid, and <code>null</code> is returned.
100: *
101: * <p>The implementation of this method in class {@link FunctionResult}
102: * always returns <code>null</code>.
103: *
104: * @return
105: * an {@link InvalidResponseResult} instance if at least one output
106: * parameter is missing or invalid, or <code>null</code> otherwise.
107: *
108: * @since XINS 2.0.
109: */
110: public InvalidResponseResult checkOutputParameters() {
111: return null;
112: }
113:
114: /**
115: * Adds an output parameter to the result. The name and the value must
116: * both be specified.
117: *
118: * @param name
119: * the name of the output parameter, not <code>null</code> and not an
120: * empty string.
121: *
122: * @param value
123: * the value of the output parameter, not <code>null</code> and not an
124: * empty string.
125: *
126: * @throws IllegalArgumentException
127: * if <code>name == null || "".equals(name)
128: * || value == null || "".equals(value)</code>.
129: */
130: protected void param(String name, String value)
131: throws IllegalArgumentException {
132:
133: // Check preconditions
134: MandatoryArgumentChecker.check("name", name, "value", value);
135: if (name.length() < 1) {
136: throw new IllegalArgumentException("\"\".equals(name)");
137: } else if (value.length() < 1) {
138: throw new IllegalArgumentException("\"\".equals(value)");
139: }
140:
141: // This will erase any value set before with the same name.
142: _parameters.set(name, value);
143: }
144:
145: /**
146: * Gets all parameters.
147: *
148: * @return
149: * a {@link PropertyReader} containing all parameters, never <code>null</code>;
150: * the keys will be the names of the parameters
151: * ({@link String} objects, cannot be <code>null</code>),
152: * the values will be the parameter values
153: * ({@link String} objects as well, cannot be <code>null</code>).
154: */
155: public PropertyReader getParameters() {
156: return _parameters;
157: }
158:
159: /**
160: * Gets the value of the specified parameter.
161: *
162: * @param name
163: * the parameter element name, cannot be <code>null</code>.
164: *
165: * @return
166: * string containing the value of the parameter element,
167: * or <code>null</code> if the value is not set.
168: *
169: * @throws IllegalArgumentException
170: * if <code>name == null</code>.
171: */
172: public String getParameter(String name)
173: throws IllegalArgumentException {
174:
175: // Check preconditions
176: MandatoryArgumentChecker.check("name", name);
177:
178: return _parameters.get(name);
179: }
180:
181: /**
182: * Adds a new <code>Element</code> to the data element.
183: *
184: * @param element
185: * the new element to add to the result, cannot be <code>null</code>.
186: *
187: * @throws IllegalArgumentException
188: * if <code>element == null</code>.
189: *
190: * @since XINS 1.1.0
191: */
192: protected void add(Element element) throws IllegalArgumentException {
193:
194: // Check preconditions
195: MandatoryArgumentChecker.check("element", element);
196:
197: // Lazily initialize _dataElementBuilder
198: if (_dataElementBuilder == null) {
199: _dataElementBuilder = new ElementBuilder("data");
200: }
201: _dataElementBuilder.addChild(element);
202: }
203:
204: /**
205: * Gets the data element from this result.
206: *
207: * @return
208: * the data element of the result, can be <code>null</code>.
209: */
210: public Element getDataElement() {
211: if (_dataElementBuilder == null) {
212: return null;
213: } else {
214: return _dataElementBuilder.createElement();
215: }
216: }
217:
218: public String toString() {
219: String asString = "";
220: if (_code != null) {
221: asString += "Error code: " + _code + "; ";
222: } else {
223: asString += "Successful result; ";
224: }
225: asString += PropertyReaderUtils.toString(_parameters,
226: "no parameters")
227: + "; ";
228: if (_dataElementBuilder == null) {
229: asString += "no data section";
230: } else {
231: asString += _dataElementBuilder.createElement().toString();
232: }
233: return asString;
234: }
235: }
|