001: /*
002: * $Id: XINSCallResult.java,v 1.26 2007/03/15 17:08:27 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 org.xins.common.MandatoryArgumentChecker;
010: import org.xins.common.service.CallExceptionList;
011: import org.xins.common.service.CallResult;
012: import org.xins.common.service.TargetDescriptor;
013: import org.xins.common.collections.PropertyReader;
014: import org.xins.common.xml.Element;
015:
016: /**
017: * Successful result of a call to a XINS service. It may be that some targets
018: * failed before a target returned a successful result. All the failures are
019: * also stored in this object.
020: *
021: * <p>When a <code>XINSCallResult</code> instance is created, information must
022: * be passed both about the successful call (which target successfully
023: * returned a result, how long did it take, what was the result) and about the
024: * unsuccessful calls (to which targets were they, what was the error, etc.)
025: *
026: * <p>While a {@link XINSCallResultData} object describes the result of a call
027: * to an single target, a <code>XINSCallResultData</code> also describes all
028: * failed calls that happened before.
029: *
030: * @version $Revision: 1.26 $ $Date: 2007/03/15 17:08:27 $
031: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
032: *
033: * @since XINS 1.0.0
034: */
035: public final class XINSCallResult extends CallResult implements
036: XINSCallResultData {
037:
038: /**
039: * The <code>XINSCallResultData</code> object that contains all the
040: * information returned from the call. This field cannot be
041: * <code>null</code>.
042: */
043: private final XINSCallResultData _data;
044:
045: /**
046: * Constructs a new <code>XINSCallResult</code> object.
047: *
048: * @param request
049: * the original {@link XINSCallRequest} that was used to perform the
050: * call, cannot be <code>null</code>.
051: *
052: * @param succeededTarget
053: * the {@link TargetDescriptor} that was used to successfully get the
054: * result, cannot be <code>null</code>.
055: *
056: * @param duration
057: * the call duration, should be >= 0.
058: *
059: * @param exceptions
060: * the list of {@link org.xins.common.service.CallException}s, collected
061: * in a {@link CallExceptionList} object, or <code>null</code> if the
062: * first call attempt succeeded.
063: *
064: * @param data
065: * the {@link XINSCallResultData} returned from the call, cannot be
066: * <code>null</code>.
067: *
068: * @throws IllegalArgumentException
069: * if <code>request == null
070: * || succeededTarget == null
071: * || data == null
072: * || duration < 0</code>.
073: */
074: XINSCallResult(XINSCallRequest request,
075: TargetDescriptor succeededTarget, long duration,
076: CallExceptionList exceptions, XINSCallResultData data)
077:
078: throws IllegalArgumentException {
079:
080: super (request, succeededTarget, duration, exceptions);
081:
082: _data = data;
083: }
084:
085: /**
086: * Returns the error code. If <code>null</code> is returned the call was
087: * successful and thus no error code was returned. Otherwise the call was
088: * unsuccessful.
089: *
090: * <p>This method will never return an empty string, so if the result is
091: * not <code>null</code>, then it is safe to assume the length of the
092: * string is at least 1 character.
093: *
094: * @return
095: * the returned error code, or <code>null</code> if the call was
096: * successful.
097: */
098: public String getErrorCode() {
099: return _data.getErrorCode();
100: }
101:
102: /**
103: * Gets all parameters.
104: *
105: * @return
106: * a {@link PropertyReader} with all parameters, or <code>null</code>
107: * if there are none.
108: */
109: public PropertyReader getParameters() {
110: return _data.getParameters();
111: }
112:
113: /**
114: * Gets the value of the specified parameter.
115: *
116: * @param name
117: * the parameter element name, not <code>null</code>.
118: *
119: * @return
120: * string containing the value of the parameter element,
121: * or <code>null</code> if the parameter has no value.
122: *
123: * @throws IllegalArgumentException
124: * if <code>name == null</code>.
125: */
126: public String getParameter(String name)
127: throws IllegalArgumentException {
128:
129: // Check preconditions
130: MandatoryArgumentChecker.check("name", name);
131:
132: PropertyReader params = getParameters();
133:
134: // Short-circuit if there are no parameters at all
135: if (params == null) {
136: return null;
137: }
138:
139: // Otherwise return the parameter value
140: return params.get(name);
141: }
142:
143: /**
144: * Returns the optional extra data. The data is an XML {@link Element},
145: * or <code>null</code>.
146: *
147: * @return
148: * the extra data as an XML {@link Element}, can be
149: * <code>null</code>.
150: */
151: public Element getDataElement() {
152: return _data.getDataElement();
153: }
154: }
|