User can white list or black list a set of methods in a POJO service. White and black listing is done using the filter attribute of the methods element in the POJO element. The values of the filter can be whitelisting and blacklisting. If the filter is not specified, all the methods are listed. The getAddress method of the AddressLookup class can be white listed by specifying the POJO service as in the following example.
The example demonstrates that only getAddress of the AddressLookup class is accessible using RPC adapter. The same method can be black listed as in the following example.
The previous example demonstrates that all methods of the AddressLookup class, except getAddress are accessible using RPC adapter. If the methods element of POJO service is not specified or the filter attribute is not specified for the methods element then by default all methods are white listed.
In many cases, you might need to access the HttpServletRequest object in the methods that you are calling from JavaScriptTM. This can be accomplished in the RPC adapter by having the HttpServletRequest as the first parameter in the method call. The simple method description (SMD) that is returned does not have the HttpServletRequest object as a parameter and you can call the method from JavaScript without passing this parameter. For example, consider a method putNameInSession(HttpServletRequest req, String name). The following corresponding XML is displayed.
Validators are defined by using the validators elements in the RPC adapter configuration file. You can specify a set of validators for individual POJO services. Before invocation of a method, the validate method of the specified validator is called on the parameters of the method. You can specify separate validators for each method parameter. All of the validators extend the abstract class com.ibm.websphere.rpcadapter.Validator. Another way of validating is by using regular expressions. The validation-regex element can be used to specify regular expressions that match the parameter values. If the parameter values are not matching the regular expression then a validation error is created.
Validation errors result in an Error object being returned in JSON format. This information can be used for error handling. The fields are described below.
The RPC adapter now supports scopes for the objects that it exposes. There are three different scopes that are supported by RPC adapter namely Request, Session and Application which can be specified to store the exposed object in the request, session or application. When the scope is set to Application or Session then an additional advantage is that the object is not recreated every time but looked up from the Session or Application scope. The key used is of the format "com.ibm.websphere.rpcadapter:ServiceName" where ServiceName is the name of exposed object. In order to specify this key the scope tag is provided for each object and this tag may contain the values: Session, Request and Application. See the following example.
The RPC adapter now supports you adding return values to the session. To enable this value add, the <add-to-session> tag needs to be added as shown below.
The RPC adapter now supports complex objects, for example, objects that can contain other objects. Complex objects are supported as return types as well as method parameters. RPC adapter can now serialize any type of complex object. Maps and Collections are not supported as parameters to method calls. This is because the class of the objects contained in the Map or Collection cannot be identified from its contents alone. Support for this will require class hinting or parameterized types and is not yet supported. Also you cannot call methods with complex parameters via HTTP-RPC though complex return types are supported.
This is a particular case of complex object support. For example, A -> B -> A or A contains B which contains A. The product RPC Adapter component handles this case by replacing the duplicate occurrences of objects with $jref (JSON serialization) or $xref (XML Serialization) placeholders. These place holders contain information that can be used to lookup the original object i.e. an XPath expression in the case of XML and a JavaScript expression in the case of JSON. The support for recursive object handling can be turned on by setting the value of the <recursive-object-support> tag to true. This is shown in the following example.
Often the objects that need to be exposed may have certain fields that the application developer does not want to expose through the JSON or XML Web service. RPC adapter provides the ability to suppress fields from the returned object. This suppression of fields can be enabled by means of the tag <serialized-params>. The configuration required to suppress the postalCode field of the com.ibm.Address class is shown below. This configuration results in the postalCode field of the com.ibm.Address class never being serialized.
The user can specify aliases for classes. The alias is used as node name during XML serialization. The following example shows how the alias for address can be configured.
User can specify convertors for JSON/XML. If a convertor is specified for a class, the convertor will be used for JSON/XML
serialization of that class. All the convertor classes need to implement com.ibm.websphere.rpcadapter.converters.IConverter
interface. By default RPC adapter comes with the following convertors.
Converter | Usage |
com.ibm.websphere.rpcadapter.converters.sql.Date
|
To convert java.sql.Date to date and time string. |
com.ibm.websphere.rpcadapter.converters.sql.Time
|
To convert java.sql.Time to date and time string. |
com.ibm.websphere.rpcadapter.converters.sql.TimeStamp
|
To convert java.sql.TimeStamp to date and time string. |
com.ibm.websphere.rpcadapter.converters.util.Date
|
To convert java.util.Date to date and time string. |
You can specify convertors in RpcAdapterConfig.xml similar to the following example.The <subclass-support> tag can be used to specify that even the subclasses of the bean-class specified should be converted by the converter-class by setting the value between the tags to true. By default this is set as false.
For security reasons, RPC adapter can be configured to emit JSON comment filtered output when used for exposing methods as JSON Web services, such as, JSON data wrapped with '/*' and '*/'. Dojo has the ability to process this comment filtered JSON at the client side. By default this feature is disabled in the RPCAdapter. It can be enabled by setting the filtered tag to true in the RPCAdapterConfig.xml file as shown in the following example.
Security support in the RPC adapter is achieved using Java EE Web security. All of the services that have been configured to be exposed to the client will have unique URLs. Access to these URLs are restricted by using Java EE Web security. This involves creating a security realm in the Application Server and then defining role based access to different URLs in the deployment descriptor file, web.xml, and then mapping these roles to users or groups in the security-realm using a server specific configuration. This feature cannot be used in isolation for batched calls.
In addition to the Java EE Web Security, the RPCAdapter also can be configured to perform authorization checks for the exposed services and consequently allow access only to specific roles defined in the web.xml or the geronimo-web.xml. In order to use this feature, the "/RPCAdapter/*" url-pattern should be secured through the web.xml. The next step involves using the <role> tag to specify if only a user in a particular role will be allowed access to the corresponding service. It should be noted that while RPCAdapter performs service authorization, it still remains the responsibility of the application to authenticate the user before the secured service is called. If authentication is not done before the secured service is called, RPCAdapter will not allow access to the corresponding service. This is applicable only for methods in the service which are already whitelisted. Access to a service can be controlled as shown below.
Users can batch a set of calls using the BatchService API. A new batch service factory can be created, initialized and then submitted as follows.
Overloaded methods can be exposed by specifying a unique name for a given overloaded method and the corresponding parameter types in the RpcAdapterConfig.xml file.
Methods can be assigned names that are different from the actual ones used in the Java implementation. This can be done by using the <alias> and <name> tags in a similar manner as used for method overloading. The only exception being that the parameter types do not have to be specified if the method is not overloaded.
To access enterprise beans through the RPCAdapter, specify necessary information of EJB module in RPCAdapterConfig.xml. The methods in EJB module are exposed and you can invoke a method directly from JavaScript.
To access Session beans thorugh the RPCAdapter, specify the remote and local interfaces, the jndi-name for EJB module lookup, and the methods that are implemented. In case of EJB 3.0 remote and local interface are
replaced by a single interface usually called business-interface. Therefore, specify business interface using the <business-interface> tag. <ejb-name> tag is used to associate a logical name to EJB
module. The <jndi-name> is used to lookup EJB modules. The jndi-name specified by the user in RPCAdapterConfig.xml file must match with the jndi-name specified in the web.xml file. In case of EJB 3.0, prefix
the jndi-name with "java:comp/env/" if the Application Server used is WebSphere® Application Server Community Edition. In case of WebSphere Application Server, if EJB3.0 is being used, the jndi-name within
the <jndi-name> tag must be prefixed with the "ejblocal:" keyword. You must provide the type of session bean, either stateless or stateful, using the <session-type> tag.
An example entry for Stateless Session Bean in the RPCAdapterConfig.xml file is as shown in the following example.
In Stateful Session Beans, home interface can contain more than one create function. In such a case, specify the create function that is to be called. Use the <create> tag to declare the create function in the RPCAdapterConfig.xml file. Code snippet of Stateful Session Bean for EJB 2.1 is as follows.
Annotation support allows you to expose your services directly from the code, rather than configuring them in the RPCAdapterConfig.xml file. To enable this feature, the file RPCAdapter-annotation.jar is provided in this release. Place this jar file in the WEB-INF/lib directory of the Web application using this feature. You should annotate the class which contains the methods to be exposed with @Pojo and the corresponding methods with the @Method and @Params annotations. An annotated class is made visible to the RPCAdapter through the web.xml file. Specify the canonical name of the annotated class as an "init-param" value to the RPCAdapter. Mention the corresponding "init-param" name as classn where n is any number. Below is a sample code snippet.
In RPC adapter, the output format is either JSON or XML.
The various XML outputs that are generated under different scenarios are listed below.
If the return type is void, then the generated XML output is an empty result tag as shown below.
If the method in the JavaBeans is public int getSalary()
,the output is similar to the following:
public String getMessage()
, the output is similar to the following example.
public Boolean isLeapYear(int year)
, the output is similar to the following example.
For return type collection the output is a set of elements with each element representing an entry in the collection. If the collection contains any instances of a suppressed object type then that entry is ignored.
public Collection getEmployees()
and the returned collection contains
instances of Employee then one sample output is similar to the following example.
For return type Array the output is a set of Elements with each element representing an entry in the array.
public Employee[] getEmployees()
and the returned Array consists of instances of
Employee then one sample output is similar to the following example.
For return type of Map the output will be a set of Elements with each element representing a key value pair in the map.The node name is the key.
If the method in JavaBeans is public Map getDepartments()
and the returned map is a key value pair of department code to department details,
one sample output is similar to the following example.
For return type of JavaBeans all the read methods and public fields without a read method will be considered for XML serialization. The JavaBeans are represented by an element. The node name of this element will be the type of JavaBeans that it represents. If any alias is specified for the bean then that is used as node name.
If the method in the JavaBeans is public Employee getEmployee()
, then one sample output is similar to the following example.
The various JSON outputs generated under various scenarios are explained below.
If the return type is void, the JSON output generated is a JSON result object.
public int getSalary()
then the output is similar to the following exmaple.
public String getMessage()
then the output is similar to the following example.
public Boolean isLeapYear(int year)
then the output is similar to the following example.
For return type collection the output is a set of elements with each element representing an entry in the collection. If the collection contains any instances of a suppressed object type then that entry is ignored.
public Collection getEmployees()
and the returned collection contains instances of Employee then one sample output is similar to the following:
For return type Array the output is a set of Elements with each element representing an entry in the array.
public Employee[] getEmployees()
and the returned Array consists of instances of
Employee then one sample output is similar to the following example.
For return type of Map the output will be a set of key value pairs.
If the method in the JavaBeans is public Map getDepartments()
and the returned map is a key value pair of department code to department details, then one sample output is similar to the following example.
The JavaBeans are represented as key value pairs with the key as the name of the field and value as the value of the field. Only public fields and fields with getters are serialized.
If the method in the JavaBeans is public Employee getEmployee()
, then a sample output is similar to the following example.
The RPC adapter can be configured (1) to instantiate JavaBeans per request or (2) to reuse instances per user. (For example, a shopping cart object might be configured as the latter.) The default behavior is to instantiate new JavaBeans per request. Reuse is configured through the Bean descriptor information. See the SampleBeanInfo API documentation for details.
Some commands are developed without the expectation of being exposed directly as services. In such cases, a JavaBeans accessor can be developed to contain the implied logic. For example, the ShoppingCart EJB in the PlantsByWebSphere sample includes an addItem(StoreItem item) method. The StoreItem object includes the item price, so this design presumes that only trusted sources will invoke the method, such as the following example in the ShoppingServlet servlet.