001: /*
002: * $Id: CallContext.java,v 1.124 2007/03/15 17:08:40 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.PropertyReader;
011: import org.xins.common.xml.Element;
012:
013: /**
014: * Context for a function call. Objects of this kind are passed with a
015: * function call.
016: *
017: * @version $Revision: 1.124 $ $Date: 2007/03/15 17:08:40 $
018: * @author <a href="mailto:ernst@ernstdehaan.com">Ernst de Haan</a>
019: *
020: * @since XINS 1.0.0
021: */
022: public final class CallContext {
023:
024: /**
025: * The parameters of the request.
026: */
027: private final PropertyReader _parameters;
028:
029: /**
030: * The data section of the request.
031: */
032: private final Element _dataElement;
033:
034: /**
035: * The call result builder. Cannot be <code>null</code>.
036: */
037: private final FunctionResult _builder;
038:
039: /**
040: * The start time of the call, as a number of milliseconds since the UNIX
041: * Epoch.
042: */
043: private final long _start;
044:
045: /**
046: * The call ID, unique in the context of the pertaining function.
047: */
048: private final int _callID;
049:
050: /**
051: * The IP address of the caller.
052: */
053: private final String _remoteIP;
054:
055: /**
056: * Constructs a new <code>CallContext</code> and configures it for the
057: * specified request.
058: *
059: * @param functionRequest
060: * the request, never <code>null</code>.
061: *
062: * @param start
063: * the start time of the call, as milliseconds since the
064: * <a href="http://en.wikipedia.org/wiki/Unix_Epoch">UNIX Epoch</a>.
065: *
066: * @param function
067: * the concerning function, cannot be <code>null</code>.
068: *
069: * @param callID
070: * the assigned call ID.
071: *
072: * @param remoteIP
073: * the IP address of the caller.
074: *
075: * @throws IllegalArgumentException
076: * if <code>parameters == null || function == null</code>.
077: */
078: CallContext(FunctionRequest functionRequest, long start,
079: Function function, int callID, String remoteIP)
080: throws IllegalArgumentException {
081:
082: // Check preconditions
083: MandatoryArgumentChecker.check("functionRequest",
084: functionRequest, "function", function);
085:
086: // Initialize fields
087: _parameters = functionRequest.getParameters();
088: _dataElement = functionRequest.getDataElement();
089: _start = start;
090: _callID = callID;
091: _remoteIP = remoteIP;
092: _builder = new FunctionResult();
093: }
094:
095: /**
096: * Returns the start time of the call.
097: *
098: * @return
099: * the timestamp indicating when the call was started, as a number of
100: * milliseconds since the
101: * <a href="http://en.wikipedia.org/wiki/Unix_Epoch">UNIX Epoch</a>.
102: *
103: * @see System#currentTimeMillis()
104: */
105: public long getStart() {
106: return _start;
107: }
108:
109: /**
110: * Returns the stored return code.
111: *
112: * @return
113: * the return code, can be <code>null</code>.
114: */
115: final String getErrorCode() {
116: return _builder.getErrorCode();
117: }
118:
119: /**
120: * Returns the value of a parameter with the specificied name. Note that
121: * reserved parameters, i.e. those starting with an underscore
122: * (<code>'_'</code>) cannot be retrieved.
123: *
124: * @param name
125: * the name of the parameter, not <code>null</code>.
126: *
127: * @return
128: * the value of the parameter, or <code>null</code> if the parameter is
129: * not set, never an empty string (<code>""</code>) because it will be
130: * returned as being <code>null</code>.
131: *
132: * @throws IllegalArgumentException
133: * if <code>name == null</code>.
134: */
135: public String getParameter(String name)
136: throws IllegalArgumentException {
137:
138: // Check arguments
139: if (name == null) {
140: throw new IllegalArgumentException("name == null");
141: }
142:
143: // XXX: In a later version, support a parameter named 'function'
144:
145: if (_parameters != null && name.length() > 0
146: && !"function".equals(name) && name.charAt(0) != '_') {
147: String value = _parameters.get(name);
148: return "".equals(value) ? null : value;
149: }
150: return null;
151: }
152:
153: /**
154: * Returns the data section of the request, if any.
155: *
156: * @return
157: * the element representing the data section or <code>null</code> if the
158: * function does not define a data section or if the data section sent is
159: * empty.
160: */
161: public Element getDataElement() {
162: return _dataElement;
163: }
164:
165: /**
166: * Returns the assigned call ID. This ID is unique within the context of
167: * the pertaining function. If no call ID is assigned, then <code>-1</code>
168: * is returned.
169: *
170: * @return
171: * the assigned call ID for the function, or <code>-1</code> if none is
172: * assigned.
173: */
174: public int getCallID() {
175: return _callID;
176: }
177:
178: /**
179: * Returns the IP address of the host that requested this function.
180: *
181: * @return
182: * the IP address as a <code>String</code>.
183: */
184: public String getRemoteAddr() {
185: return _remoteIP;
186: }
187: }
|