001: /*
002: * $Id: HTTPCallResult.java,v 1.30 2007/03/16 09:54:58 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.common.http;
008:
009: import java.io.ByteArrayInputStream;
010: import java.io.InputStream;
011: import java.io.UnsupportedEncodingException;
012:
013: import org.xins.common.MandatoryArgumentChecker;
014: import org.xins.common.Utils;
015:
016: import org.xins.common.service.CallExceptionList;
017: import org.xins.common.service.CallResult;
018: import org.xins.common.service.TargetDescriptor;
019:
020: /**
021: * Result returned from an HTTP request.
022: *
023: * @version $Revision: 1.30 $ $Date: 2007/03/16 09:54:58 $
024: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
025: *
026: * @since XINS 1.0.0
027: */
028: public final class HTTPCallResult extends CallResult implements
029: HTTPCallResultData {
030:
031: /**
032: * The <code>HTTPCallResultData</code> object that contains the information
033: * returned from the call. This field cannot be <code>null</code>.
034: */
035: private final HTTPCallResultData _data;
036:
037: /**
038: * Constructs a new <code>HTTPCallResult</code> object.
039: *
040: * @param request
041: * the call request that resulted in this result, cannot be
042: * <code>null</code>.
043: *
044: * @param succeededTarget
045: * the target for which the call succeeded, cannot be <code>null</code>.
046: *
047: * @param duration
048: * the call duration in milliseconds, must be a non-negative number.
049: *
050: * @param exceptions
051: * the list of {@link CallExceptionList}s, or <code>null</code> if the
052: * first call attempt succeeded.
053: *
054: * @param data
055: * the {@link HTTPCallResultData} object returned from the call, cannot
056: * be <code>null</code>.
057: *
058: * @throws IllegalArgumentException
059: * if <code>request == null
060: * || succeededTarget == null
061: * || data == null
062: * || duration < 0L</code>.
063: *
064: * @since XINS 1.5.0
065: */
066: public HTTPCallResult(HTTPCallRequest request,
067: TargetDescriptor succeededTarget, long duration,
068: CallExceptionList exceptions, HTTPCallResultData data)
069: throws IllegalArgumentException {
070:
071: super (checkArguments(request, succeededTarget, data),
072: succeededTarget, duration, exceptions);
073:
074: _data = data;
075: }
076:
077: /**
078: * Checks the constructor arguments that cannot be <code>null</code>.
079: *
080: * @param request
081: * the call request that resulted in this result, cannot be
082: * <code>null</code>.
083: *
084: * @param succeededTarget
085: * the target for which the call succeeded, cannot be <code>null</code>.
086: *
087: * @param data
088: * the {@link HTTPCallResultData} object returned from the call, cannot
089: * be <code>null</code>.
090: *
091: * @return
092: * the argument <code>request</code>, never <code>null</code>.
093: *
094: * @throws IllegalArgumentException
095: * if <code>request == null
096: * || succeededTarget == null
097: * || data == null</code>.
098: */
099: private static HTTPCallRequest checkArguments(
100: HTTPCallRequest request, TargetDescriptor succeededTarget,
101: HTTPCallResultData data) throws IllegalArgumentException {
102:
103: // Check preconditions
104: MandatoryArgumentChecker.check("request", request,
105: "succeededTarget", succeededTarget, "data", data);
106:
107: return request;
108: }
109:
110: /**
111: * Returns the HTTP status code.
112: *
113: * @return
114: * the HTTP status code.
115: */
116: public int getStatusCode() {
117: return _data.getStatusCode();
118: }
119:
120: /**
121: * Returns the result data as a byte array. Note that this is not a copy or
122: * clone of the internal data structure, but it is a link to the actual
123: * data structure itself.
124: *
125: * @return
126: * a byte array of the result data, never <code>null</code>.
127: */
128: public byte[] getData() {
129: return _data.getData();
130: }
131:
132: /**
133: * Returns the returned data as a <code>String</code>. The encoding
134: * <code>US-ASCII</code> is assumed.
135: *
136: * @return
137: * the result data as a text string, not <code>null</code>.
138: */
139: public String getString() {
140:
141: // Get as ASCII
142: final String ENCODING = "US-ASCII";
143: try {
144: return getString(ENCODING);
145:
146: // This should never happen: ASCII encoding is not supported
147: } catch (UnsupportedEncodingException exception) {
148: String detail = "Default encoding \"" + ENCODING
149: + "\" is unsupported.";
150: throw Utils.logProgrammingError(detail, exception);
151: }
152: }
153:
154: /**
155: * Returns the returned data as a <code>String</code> in the specified
156: * encoding.
157: *
158: * @param encoding
159: * the encoding to use in the conversion from bytes to a text string,
160: * not <code>null</code>.
161: *
162: * @return
163: * the result data as a text string, not <code>null</code>.
164: *
165: * @throws UnsupportedEncodingException
166: * if the specified encoding is not supported.
167: */
168: public String getString(String encoding)
169: throws UnsupportedEncodingException {
170: byte[] bytes = getData();
171: return new String(bytes, encoding);
172: }
173:
174: /**
175: * Returns the returned data as an <code>InputStream</code>. The input
176: * stream is based directly on the underlying byte array.
177: *
178: * @return
179: * an {@link InputStream} that returns the returned data, never
180: * <code>null</code>.
181: */
182: public InputStream getStream() {
183: return new ByteArrayInputStream(getData());
184: }
185: }
|