001: /*
002: * $Id: UnacceptableResultXINSCallException.java,v 1.22 2007/05/15 11:33:19 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.collections.PropertyReader;
011: import org.xins.common.service.TargetDescriptor;
012: import org.xins.common.xml.Element;
013:
014: /**
015: * Exception that indicates that an API call returned a result that was
016: * considered unacceptable by the application layer.
017: *
018: * <p>Note that this exception is <em>not</em> thrown if the result is
019: * invalid according to the XINS rules for a result XML document. Only if the
020: * result is just invalid in relation to the applicable API specification this
021: * exception is thrown.
022: *
023: * @version $Revision: 1.22 $ $Date: 2007/05/15 11:33:19 $
024: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
025: *
026: * @since XINS 1.0.0
027: */
028: public class UnacceptableResultXINSCallException extends
029: XINSCallException {
030:
031: /**
032: * The result that is considered unacceptable. Never <code>null</code>.
033: */
034: private final XINSCallResultData _result;
035:
036: /**
037: * Constructs a new <code>UnacceptableCallResultException</code> using the
038: * specified <code>XINSCallResult</code>.
039: *
040: * @param result
041: * the {@link XINSCallResult} that is considered unacceptable, never
042: * <code>null</code>.
043: *
044: * @param detail
045: * a detailed description of why the result is considered unacceptable,
046: * or <code>null</code> if such a description is not available.
047: *
048: * @param cause
049: * the optional cause exception, or <code>null</code>.
050: *
051: * @throws IllegalArgumentException
052: * if <code>result == null</code>.
053: */
054: public UnacceptableResultXINSCallException(XINSCallResult result,
055: String detail, Throwable cause)
056: throws IllegalArgumentException {
057:
058: super ("Unacceptable XINS call result", result, detail, cause);
059:
060: // Store the result
061: _result = result;
062: }
063:
064: /**
065: * Constructs a new <code>UnacceptableCallResultException</code> using the
066: * specified <code>AbstractCAPICallResult</code>.
067: *
068: * @param result
069: * the {@link AbstractCAPICallResult} that is considered unacceptable,
070: * never <code>null</code>.
071: *
072: * @param detail
073: * a detailed description of why the result is considered unacceptable,
074: * or <code>null</code> if such a description is not available.
075: *
076: * @param cause
077: * the optional cause exception, or <code>null</code>.
078: *
079: * @throws IllegalArgumentException
080: * if <code>result == null</code>.
081: */
082: public UnacceptableResultXINSCallException(
083: AbstractCAPICallResult result, String detail,
084: Throwable cause) throws IllegalArgumentException {
085:
086: this (checkArguments(result).getXINSCallResult(), detail, cause);
087: }
088:
089: /**
090: * Constructs a new <code>UnacceptableResultXINSCallException</code> based
091: * on a <code>XINSCallResultData</code> instance.
092: *
093: * @param request
094: * the original request, cannot be <code>null</code>.
095: *
096: * @param target
097: * descriptor for the target that was attempted to be called, cannot be
098: * <code>null</code>.
099: *
100: * @param duration
101: * the call duration in milliseconds, must be >= 0.
102: *
103: * @param resultData
104: * the result data, cannot be <code>null</code>.
105: *
106: * @param detail
107: * detail message, or <code>null</code>.
108: *
109: * @throws IllegalArgumentException
110: * if <code>request == null
111: * || target == null
112: * || duration < 0
113: * || resultData == null
114: * || resultData.{@link XINSCallResult#getErrorCode() getErrorCode()} == null</code>.
115: */
116: UnacceptableResultXINSCallException(XINSCallRequest request,
117: TargetDescriptor target, long duration,
118: XINSCallResultData resultData, String detail)
119: throws IllegalArgumentException {
120:
121: super ("Unacceptable XINS call result", request, target,
122: duration, detail, (Throwable) null);
123:
124: // Check additional precondition
125: MandatoryArgumentChecker.check("resultData", resultData);
126:
127: // Store details
128: _result = resultData;
129: }
130:
131: /**
132: * Checks the mandatory <code>result</code> argument for the constructor
133: * that accepts an <code>AbstractCAPICallResult</code>.
134: *
135: * @param result
136: * the argument for the constructor, cannot be <code>null</code>.
137: *
138: * @return
139: * the argument <code>result</code>, guaranteed not <code>null</code>.
140: *
141: * @throws IllegalArgumentException
142: * if <code>result == null</code>.
143: */
144: private static AbstractCAPICallResult checkArguments(
145: AbstractCAPICallResult result)
146: throws IllegalArgumentException {
147: MandatoryArgumentChecker.check("result", result);
148: return result;
149: }
150:
151: /**
152: * Returns the error code.
153: *
154: * @return
155: * the error code or <code>null</code> if the call was successful and no
156: * error code was returned.
157: */
158: public final String getErrorCode() {
159: return _result.getErrorCode();
160: }
161:
162: /**
163: * Gets all returned parameters.
164: *
165: * @return
166: * a {@link PropertyReader} containing all parameters, or
167: * <code>null</code> if there are none.
168: */
169: public final PropertyReader getParameters() {
170: return _result.getParameters();
171: }
172:
173: /**
174: * Gets the value of the specified returned parameter.
175: *
176: * @param name
177: * the parameter name, not <code>null</code>.
178: *
179: * @return
180: * the value of the parameter, or <code>null</code> if there is no values.
181: *
182: * @throws IllegalArgumentException
183: * if <code>name == null</code>.
184: */
185: public final String getParameter(String name)
186: throws IllegalArgumentException {
187: PropertyReader p = getParameters();
188: if (p == null) {
189: return null;
190: } else {
191: return p.get(name);
192: }
193: }
194:
195: /**
196: * Returns the optional extra data.
197: *
198: * @return
199: * the extra data as an {@link Element}, can be <code>null</code>;
200: */
201: public final Element getDataElement() {
202: return _result.getDataElement();
203: }
204: }
|