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