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

    All Methods Instance Methods Concrete Methods
    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.

Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.