org.xins.server.CallContext Maven / Gradle / Ivy
/*
* $Id: CallContext.java,v 1.124 2007/03/15 17:08:40 agoubard Exp $
*
* Copyright 2003-2007 Orange Nederland Breedband B.V.
* See the COPYRIGHT file for redistribution and use restrictions.
*/
package org.xins.server;
import org.xins.common.MandatoryArgumentChecker;
import org.xins.common.collections.PropertyReader;
import org.xins.common.xml.Element;
/**
* Context for a function call. Objects of this kind are passed with a
* function call.
*
* @version $Revision: 1.124 $ $Date: 2007/03/15 17:08:40 $
* @author Ernst de Haan
*
* @since XINS 1.0.0
*/
public final class CallContext {
/**
* The parameters of the request.
*/
private final PropertyReader _parameters;
/**
* The data section of the request.
*/
private final Element _dataElement;
/**
* The call result builder. Cannot be null.
*/
private final FunctionResult _builder;
/**
* The start time of the call, as a number of milliseconds since the UNIX
* Epoch.
*/
private final long _start;
/**
* The call ID, unique in the context of the pertaining function.
*/
private final int _callID;
/**
* The IP address of the caller.
*/
private final String _remoteIP;
/**
* Constructs a new CallContext and configures it for the
* specified request.
*
* @param functionRequest
* the request, never null.
*
* @param start
* the start time of the call, as milliseconds since the
* UNIX Epoch.
*
* @param function
* the concerning function, cannot be null.
*
* @param callID
* the assigned call ID.
*
* @param remoteIP
* the IP address of the caller.
*
* @throws IllegalArgumentException
* if parameters == null || function == null.
*/
CallContext(FunctionRequest functionRequest,
long start,
Function function,
int callID,
String remoteIP)
throws IllegalArgumentException {
// Check preconditions
MandatoryArgumentChecker.check("functionRequest", functionRequest,
"function", function);
// Initialize fields
_parameters = functionRequest.getParameters();
_dataElement = functionRequest.getDataElement();
_start = start;
_callID = callID;
_remoteIP = remoteIP;
_builder = new FunctionResult();
}
/**
* Returns the start time of the call.
*
* @return
* the timestamp indicating when the call was started, as a number of
* milliseconds since the
* UNIX Epoch.
*
* @see System#currentTimeMillis()
*/
public long getStart() {
return _start;
}
/**
* Returns the stored return code.
*
* @return
* the return code, can be null.
*/
final String getErrorCode() {
return _builder.getErrorCode();
}
/**
* Returns the value of a parameter with the specificied name. Note that
* reserved parameters, i.e. those starting with an underscore
* ('_') cannot be retrieved.
*
* @param name
* the name of the parameter, not null.
*
* @return
* the value of the parameter, or null if the parameter is
* not set, never an empty string ("") because it will be
* returned as being null.
*
* @throws IllegalArgumentException
* if name == null.
*/
public String getParameter(String name)
throws IllegalArgumentException {
// Check arguments
if (name == null) {
throw new IllegalArgumentException("name == null");
}
// XXX: In a later version, support a parameter named 'function'
if (_parameters != null && name.length() > 0 && !"function".equals(name) && name.charAt(0) != '_') {
String value = _parameters.get(name);
return "".equals(value) ? null : value;
}
return null;
}
/**
* Returns the data section of the request, if any.
*
* @return
* the element representing the data section or null if the
* function does not define a data section or if the data section sent is
* empty.
*/
public Element getDataElement() {
return _dataElement;
}
/**
* Returns the assigned call ID. This ID is unique within the context of
* the pertaining function. If no call ID is assigned, then -1
* is returned.
*
* @return
* the assigned call ID for the function, or -1 if none is
* assigned.
*/
public int getCallID() {
return _callID;
}
/**
* Returns the IP address of the host that requested this function.
*
* @return
* the IP address as a String.
*/
public String getRemoteAddr() {
return _remoteIP;
}
}