oracle.adf.view.rich.remote

Class RemoteApplicationRequest

java.lang.Object

oracle.adf.view.rich.remote.RemoteApplicationRequest

All Implemented Interfaces:

Serializable

public class RemoteApplicationRequest
extends Object
implements Serializable

This is the request object into the remote application. This object contains all of the information needed to actually execute a remote task flow or other producer logic.

Asside from standard request artifacts (like cookies and headers and whatnot), this Object supports "tasks". Tasks are units of work which can be added to the request on an as-needed basis, and allow information be be exchanged between consumer and producer as well as custom code to be executed. The RegionComponent provides the ability for different pieces of ADF to add tasks to each request by creating these task invocations. The system typically works as follows:

String responseId = remoteApplicationRequest.addTask(MyRemoteTaskHandler.class, param1, param2, param3); RemoteApplicationResponse remoteApplicationResponse = RemoteApplicationUtils.run(remoteApplicationRequest); Object fromHandler = remoteApplicationResponse.getTaskResponse(responseId);

Obviously this is a simplistic usecase, but essentially what happens is the task is added to the remote request. That executes a TaskHandler called MyRemoteTaskHandler on the producer which could do setup with the specified params before the faces lifecycle is run. It can then return a result after the faces lifecycle is run which is then retrieved from the response. It is in this way that the RemoteApplication system can be extended in functionality while allowing the base protocol and framework to remain relatively lean. Note: by default the RemoteApplicationRequest does not serialize the headers as part of its serialization stream. That is because, typically, these headers will be transmitted as part of the HTTP request. It is expected that frameworks which need to serialize this object will exchange the headers themselves. If this is not done, the header methods are expected to return an IllegalStateException. RemoteApplicationUtils and its subsequent filter should ensure the header map is restored.

Since:

12.1.4

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RemoteApplicationRequest.Operation An enumeration of request types.

Constructor Summary

Constructors

Constructor and Description
RemoteApplicationRequest(RemoteApplication app) Constructs a new "INVOKE" RemoteApplicationRequest that will be used to run invoke type tasks on a producer.
RemoteApplicationRequest(RemoteApplication app, RemoteApplicationRequest.Operation operation, String resource) Constructs a new RemoteApplicationRequest for a given Operation that will be used to make a connection to the producer.
RemoteApplicationRequest(RemoteApplication app, RemoteApplicationRequest.Operation operation, String resource, Iterator<Locale> locales) Constructs a new RemoteApplicationRequest for a given Operation that will be used to make a connection to the producer.
RemoteApplicationRequest(RemoteApplicationRequest req, Map<String,List<String>> headers) This is a copy constructor that can re-unite a RemoteApplicationRequest with its headers.
RemoteApplicationRequest(RemoteApplication app, String resource) Constructs a new "EXECUTE" RemoteApplicationRequest that will be used to run a resource on the producer.

Method Summary

Modifier and Type	Method and Description
void	addCookie(javax.servlet.http.Cookie cookie) Adds a cookie to this request
void	addCookies(List<? extends javax.servlet.http.Cookie> cookies) Adds a list of cookies to this request
void	addHeader(String name, String value) Add's a header to the header map.
void	addHeaders(String name, String[] values) This add's multiple headers with the same name to this request.
String	addOptionalTask(Class<? extends TaskHandler> taskHandler, Serializable defaultValue, Serializable... parameters) Adds a task to this request.
String	addOptionalTask(String taskHandler, Serializable defaultValue, Serializable... parameters) Adds a task to this request.
String	addTask(Class<? extends TaskHandler> taskHandler, Serializable... parameters) Adds a task to this request.
String	addTask(String taskHandler, Serializable... parameters) Adds a task to this request.
void	clearCookies() Clears all the stored cookies on this request
List<? extends javax.servlet.http.Cookie>	getCookies() Returns an unmodifiable list of cookies which need to be sent back to to the remote application during this request.
String	getHeader(String header) Returns a single header value.
Map<String,List<String>>	getHeaderMap() Returns a map of headers.
List<String>	getHeaderValues(String header) Returns all of the values of a header.
List<Locale>	getLocales() Returns an unmodifiable list of locales that passed into its constructor This list is generally assumed to be listed according to importance with the default encoding being the first element.
String	getMethod() Returns the 'simulated' method of this remote request.
RemoteApplicationRequest.Operation	getOperation() Returns the operation which is to be performed by this request.
Map<String,String[]>	getParameterMap() Returns the parameter map used for this request.
String	getQueryString() Returns the current query string of this instance.
RemoteApplication	getRemoteApplication() Returns the RemoteApplication or the RemoteApplicationInstance used to create this class.
String	getResource() Returns the resource that should be retrieved by this RemoteApplicationRequest
List<TaskInvocation>	getTaskInvocations() Returns an unmodifiable list of TaskInvocation objects.
Map<String,List<org.apache.myfaces.trinidad.model.UploadedFile>>	getUploadedFileMap() Returns a list of UploadedFiles which should be sent as part of this request.
protected void	initHeaderMap(Map<String,List<String>> m) This protected method can be used to construct a case insensitive header map after serialization so that the header functions will not throw an IllegalArgumentException.
void	setMethod(String method) Sets the 'simulated' request method for this request.
protected void	setParameterMap(Map<String,String[]> m) This is used internally for the copy constructor and any other implementation which may need to directly set the parameterMap.
void	setQueryString(String queryString) Sets the query string of this request.
protected void	setTaskInvocations(List<TaskInvocation> invocations)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RemoteApplicationRequest

public RemoteApplicationRequest(RemoteApplication app)

Constructs a new "INVOKE" RemoteApplicationRequest that will be used to run invoke type tasks on a producer.

Parameters:

app - the RemoteApplication object representing the producer

Throws:

NullPointerException - if the app property is null

RemoteApplicationRequest

public RemoteApplicationRequest(RemoteApplication app,
                                String resource)

Constructs a new "EXECUTE" RemoteApplicationRequest that will be used to run a resource on the producer.

Parameters:

app - the RemoteApplication object representing the producer

resource - the Resource to execute on the remote producer. This resource will be added to the url that is already present on the app representing the filter mapping.

Throws:

NullPointerException - if either the app or the Resource is null

RemoteApplicationRequest

public RemoteApplicationRequest(RemoteApplication app,
                                RemoteApplicationRequest.Operation operation,
                                String resource)

Constructs a new RemoteApplicationRequest for a given Operation that will be used to make a connection to the producer.

Parameters:

app - the RemoteApplication object representing the producer

operation - the Operation to perform in the remote application

resource - the Resource to execute on the remote producer. This resource will be added to the url that is already present on the app representing the filter mapping. If this is an "invoke" type request, this property is ignored.

Throws:

NullPointerException - if the app or the operation is null

IllegalArgumentException - is resource is null and operation is NOT "INVOKE".

RemoteApplicationRequest

public RemoteApplicationRequest(RemoteApplicationRequest req,
                                Map<String,List<String>> headers)

This is a copy constructor that can re-unite a RemoteApplicationRequest with its headers. This typically needs to be done after serialization to ensure that the header methods do not throw an IllegalStateException.

Parameters:

req - The request Object

headers - Map of headers.

RemoteApplicationRequest

public RemoteApplicationRequest(RemoteApplication app,
                                RemoteApplicationRequest.Operation operation,
                                String resource,
                                Iterator<Locale> locales)

Constructs a new RemoteApplicationRequest for a given Operation that will be used to make a connection to the producer.

Parameters:

app - the RemoteApplication object representing the producer

operation - the Operation to perform in the remote application

resource - the Resource to execute on the remote producer. This resource will be added to the url that is already present on the app representing the filter mapping. If this is an "invoke" type request, this property is ignored.

locales - an iterator containing a list of locales.

Throws:

NullPointerException - if the app or the operation is null

IllegalArgumentException - is resource is null and operation is NOT "INVOKE".

Method Detail

getRemoteApplication

public RemoteApplication getRemoteApplication()

Returns the RemoteApplication or the RemoteApplicationInstance used to create this class.

Returns:

the RemoteApplication or RemoteApplicationInstance

getOperation

public RemoteApplicationRequest.Operation getOperation()

Returns the operation which is to be performed by this request. Currently there are two types of requests: INVOKE and EXECUTE. The differences between these request types are listed under RemoteApplicationRequest.Operation.

Returns:

the current operation to be performed by this request.

getResource

public String getResource()

Returns the resource that should be retrieved by this RemoteApplicationRequest

Returns:

the current resource associated with this request. This should only be null for "INVOKE" type requests.

setMethod

public void setMethod(String method)

Sets the 'simulated' request method for this request. In the RemoteApplication framework, all requests to a producer are 'post' requests. Some frameworks on the producer side however, like JSF, have different behavior based on whether a request is a post or a get. This method is what is returned from the HttpServletRequest.getMetho() on the producer. Valid methods are: GET, POST, HEAD, OPTIONS, PUT, DELETE, or TRACE. The default is GET.

Parameters:

method - the 'simulated' method of the remote request.

getMethod

public String getMethod()

Returns the 'simulated' method of this remote request.

Returns:

the name of the method used.

getLocales

public List<Locale> getLocales()

Returns an unmodifiable list of locales that passed into its constructor This list is generally assumed to be listed according to importance with the default encoding being the first element. This is how the RemoteApplicationFramework will treat the list. If the list is empty, it means that no locales have been explicitly set or that the locales have been cleared.

Returns:

a List of Locales.

getCookies

public List<? extends javax.servlet.http.Cookie> getCookies()

Returns an unmodifiable list of cookies which need to be sent back to to the remote application during this request. These will be appended to the cookies which are stored on the instance and represent per-request cookie state rather then persisted cookie state.

It is important to note that these cookies will be transmitted as real cookies across the HttpRequest, so setting cookies here should be sufficient for interacting with any 'front-end' servers or proxies which may get the request before it is sent to the final endpoint.

Returns:

a list of Cookies which will be appended

clearCookies

public void clearCookies()

Clears all the stored cookies on this request

addCookie

public void addCookie(javax.servlet.http.Cookie cookie)

Adds a cookie to this request

Parameters:

cookie - the cookie

addCookies

public void addCookies(List<? extends javax.servlet.http.Cookie> cookies)

Adds a list of cookies to this request

Parameters:

cookies - The list of cookies.

setQueryString

public void setQueryString(String queryString)

Sets the query string of this request. Generally speaking this querystring overrides any that is specified in the RemoteApplicationInstance. Items in this querystring will automatically be added as parameters to the remote request. TODO: Do we need these to actually be on the URL? I think not, simulating them should be fine

Parameters:

queryString - a valid queryString without the leading "?".

getQueryString

public String getQueryString()

Returns the current query string of this instance. The parameters in this queryString will also be added as parameters automatically.

Returns:

a valid queryString or null if there isn't one

getParameterMap

public Map<String,String[]> getParameterMap()

Returns the parameter map used for this request. Using this mechanism, the request is able to simulate "post" data. Note: this information will not be xmitted across the wire as post data, but it will appear in the HttpServletRequest as such.

Returns:

a Map that should be sufficient for storing post parameter data

setParameterMap

protected void setParameterMap(Map<String,String[]> m)

This is used internally for the copy constructor and any other implementation which may need to directly set the parameterMap. Otherwise, use getParameterMap and modify values on there directly.

Parameters:

m - The paramater map.

getHeaderMap

public Map<String,List<String>> getHeaderMap()

Returns a map of headers. These headers will be transmitted as part of the physical http request, so they will be suitable for interacting with external frameworks like the one used for authorization. The format of this map is kind of strange in that it returns a list of String's for it's value. The reason for this is to support headers that may appear in the HttpRequest more then once. Generally speaking, a the value should be a single value. For more convenient access, there are several convenience methods provided. The map returned will have keys that can be accessed in a case insensitive fashion. This means that values may be retrieved regardless of the case of the string. This corresponds with the way headers work on the HttpServletRequest.

Returns:

a Map of headers

Throws:

IllegalStateException - if this object was serialized and the header map was not manually restored.

addHeader

public void addHeader(String name,
                      String value)

Add's a header to the header map. If added before the request is made, this header will be appended to the header of the HTTP Request, making it able to be used with external frameworks which may run before items are dispatched to this webapp. An example of these systems would be authorization-type systems. The name of the header will be converted to lower case when saved, and access to the header elements will be case insensitive.

Parameters:

name - the name of the header

value - the value of the header

Throws:

IllegalStateException - if this object was serialized and the header map was not manually restored.

addHeaders

public void addHeaders(String name,
                       String[] values)

This add's multiple headers with the same name to this request. The name of the header will be converted to lower case when saved, and access to the header elements will be case insensitive.

Parameters:

name - The header name.

values - Array of headers to be associated with the name.

Throws:

IllegalStateException - if this object was serialized and the header map was not manually restored.

getHeader

public String getHeader(String header)

Returns a single header value. If the header is not present, this function returns null. If the headers are present then the value of the first occurance of this header is returned. The name of the header will be converted to lower case when saved, and access to the header elements will be case insensitive.

Parameters:

header - The header name.

Returns:

A single header value. If the header is not present, this function returns null.

Throws:

IllegalStateException - if this object was serialized and the header map was not manually restored.

getHeaderValues

public List<String> getHeaderValues(String header)

Returns all of the values of a header. If there are no values for the header, the header returns an empty list. The name of the header will be converted to lower case when saved, and access to the header elements will be case insensitive.

Parameters:

header - The header name.

Returns:

a list of header values for the given header

Throws:

IllegalStateException - if this object was serialized and the header map was not manually restored.

addTask

public String addTask(String taskHandler,
                      Serializable... parameters)

Adds a task to this request. The value returned will be a unique idenifier that will be used to refer to the results returned from this task.

Parameters:

taskHandler - a string representing the classname of the handler being invoked

parameters - a list of parameters

Returns:

a String containing an id that will return the results of this tasks invocation

Throws:

UnsupportedOperationException - id this method is not supported for the type of request. Currently "fetch" type requests do not support task execution.

addTask

public String addTask(Class<? extends TaskHandler> taskHandler,
                      Serializable... parameters)

Adds a task to this request. The value returned will be a unique idenifier that will be used to refer to the results returned from this task.

Parameters:

taskHandler - a Class representing the classname of the handler being invoked

parameters - a list of parameters

Returns:

a String containing an id that will return the results of this tasks invocation

Throws:

UnsupportedOperationException - id this method is not supported for the type of request. Currently "fetch" type requests do not support task execution.

addOptionalTask

public String addOptionalTask(String taskHandler,
                              Serializable defaultValue,
                              Serializable... parameters)

Adds a task to this request. Unlike the addTask(java.lang.Class, java.io.Serializable...) method, this task handler will only be executed IF it exists on the producer. If the task handler does not exist on the producer, execution continues but the default value is returned to the consumer instead. Note: There are a couple of caviats to this API. First off, if the supplied task handler is not an instance of a TaskHandler OR if there was something wrong with instantiation, a TaskError response will be returned.

Parameters:

taskHandler - The task handler

defaultValue - If no paramter is available this default is used

parameters - The parameters for the task.

Returns:

The task naame.

addOptionalTask

public String addOptionalTask(Class<? extends TaskHandler> taskHandler,
                              Serializable defaultValue,
                              Serializable... parameters)

Adds a task to this request. Unlike the addTask(String,Serializable...) method, this task handler will only be executed IF it exists on the producer. If the task handler does not exist on the producer, execution continues but the default value is returned to the consumer instead. Note: There are a couple of caviats to this API. First off, if the supplied task handler is not an instance of a TaskHandler OR if there was something wrong with instantiation, a TaskError response will be returned.

Parameters:

taskHandler - The task handler

defaultValue - The default value if no paramters are sent in.

parameters - The parameters for the task.

Returns:

The task name

getTaskInvocations

public List<TaskInvocation> getTaskInvocations()

Returns an unmodifiable list of TaskInvocation objects.

Returns:

a list of invocations for the current request

setTaskInvocations

protected void setTaskInvocations(List<TaskInvocation> invocations)

getUploadedFileMap

public Map<String,List<org.apache.myfaces.trinidad.model.UploadedFile>> getUploadedFileMap()

Returns a list of UploadedFiles which should be sent as part of this request. UploadedFile objects which are stored in this map do not need to be serializable, but any opaqueData they contain should be serializable or the request will fail.

Returns:

a Map where all of the UploadedFile instances should be stored.

initHeaderMap

protected void initHeaderMap(Map<String,List<String>> m)

This protected method can be used to construct a case insensitive header map after serialization so that the header functions will not throw an IllegalArgumentException. Executing this method will always construct a new map which will replace the old one. If the parameter provided is null or an empty list then an empty set of headers will be provided.

Parameters:

m - Case insesitive header map.