com.ibm.websphere.rsadapter
Interface WSProceduralPushDownHelper

All Superinterfaces:
WSPushDownHelper

public interface WSProceduralPushDownHelper
extends WSPushDownHelper

This interface provides helper methods that can be used by customers in their implementations of their UserDefinedPushDownMethods classes. This sub-interface adds procedural-specific helpers beyond the generic helpers available in the super-interface.

Since:
WBI-SF 5.1

Method Summary
 javax.resource.cci.MappedRecord createCCIMappedRecord()
          This method returns an empty MappedRecord object that the caller will need to fill in with the appropriate data (which will be used by the JCA CCI interaction).
 WSStreamableRecord createCCIStreamableRecord()
          This method returns an empty Record object that implements the CCI Streamable interface, that the caller will need to fill in with the appropriate data (which will be used by the JCA CCI interaction).
 javax.resource.cci.Record executeCCIInteraction(java.lang.Object conn, javax.resource.cci.InteractionSpec spec, javax.resource.cci.Record input)
          This method executes a JCA CCI interaction.
 org.apache.wsif.WSIFMessage executeWSIFOperation(org.apache.wsif.WSIFService service, org.apache.wsif.WSIFMessage message, java.lang.String operationName, java.lang.String inputName, java.lang.String outputName)
          This method invokes a web service using WSIF APIs.
 java.lang.Object getEJBHome(java.lang.String ejbRefName, java.lang.Class homeClass)
          This method returns an EJB home object for the specified EJB, and is is used by CMP beans that defer their persistence to other EJBs.
 java.lang.Object invokeJAXRPCCall(javax.xml.rpc.Service service, javax.xml.namespace.QName port, javax.xml.namespace.QName operation, javax.xml.namespace.QName returnType, java.lang.String endpointAddress, java.lang.Object[] params)
          This method invokes a web service using JAX-RPC DII APIs.
 java.lang.Object[] invokeJService(java.lang.String serviceName, java.lang.String methodName, java.lang.Object[] input)
          This method invokes a JService using its DII APIs.
 void returnCCIMappedRecord(javax.resource.cci.MappedRecord record)
          This method returns the specified MappedRecord object to the cache.
 void returnCCIStreamableRecord(WSStreamableRecord record)
          This method returns the specified Streamable Record object to the cache.
 
Methods inherited from interface com.ibm.websphere.rsadapter.WSPushDownHelper
createCCIIndexedRecord, createCCIRecord, createResourceException, createResourceException, returnCCIIndexedRecord
 

Method Detail

createCCIMappedRecord

public javax.resource.cci.MappedRecord createCCIMappedRecord()
                                                      throws javax.resource.ResourceException

This method returns an empty MappedRecord object that the caller will need to fill in with the appropriate data (which will be used by the JCA CCI interaction).

Returns:
An empty CCI MappedRecord
Throws:
javax.resource.ResourceException - thrown if a MappedRecord could not be created.
Since:
WBI-SF 5.1

returnCCIMappedRecord

public void returnCCIMappedRecord(javax.resource.cci.MappedRecord record)
                           throws javax.resource.ResourceException

This method returns the specified MappedRecord object to the cache. Use this method only if you know that this MappedRecord is no longer used and can be safely returned back to the cache and readied for future use.

Parameters:
record - The CCI MappedRecord to return to the cache
Throws:
javax.resource.ResourceException - thrown if the MappedRecord could not be returned to the cache.
Since:
WBI-SF 5.1

createCCIStreamableRecord

public WSStreamableRecord createCCIStreamableRecord()
                                             throws javax.resource.ResourceException

This method returns an empty Record object that implements the CCI Streamable interface, that the caller will need to fill in with the appropriate data (which will be used by the JCA CCI interaction).

Returns:
An empty CCI Streamable Record
Throws:
javax.resource.ResourceException - thrown if a StreamableRecord could not be created.
Since:
WBI-SF 5.1

returnCCIStreamableRecord

public void returnCCIStreamableRecord(WSStreamableRecord record)
                               throws javax.resource.ResourceException

This method returns the specified Streamable Record object to the cache. Use this method only if you know that this Streamable Record is no longer used and can be safely returned back to the cache and readied for future use.

Parameters:
record - The CCI Streamable Record to return to the cache
Throws:
javax.resource.ResourceException - thrown if the Streamable Record could not be returned to the cache.
Since:
WBI-SF 5.1

executeCCIInteraction

public javax.resource.cci.Record executeCCIInteraction(java.lang.Object conn,
                                                       javax.resource.cci.InteractionSpec spec,
                                                       javax.resource.cci.Record input)
                                                throws javax.resource.ResourceException

This method executes a JCA CCI interaction.

Parameters:
conn - The connection to the JCA backend system
Returns:
Record The CCI record returned from the JCA interaction
Throws:
javax.resource.ResourceException - Any exception raised by the interaction with the JCA adapter will be a subclass of ResourceException and will just be allowed to flow back to the caller.
Since:
WBI-SF 5.1

getEJBHome

public java.lang.Object getEJBHome(java.lang.String ejbRefName,
                                   java.lang.Class homeClass)
                            throws javax.resource.ResourceException

This method returns an EJB home object for the specified EJB, and is is used by CMP beans that defer their persistence to other EJBs.

Note that the implementation of this method caches the home object to improve performance on subsequent usage.

Parameters:
ejbRefName - The name of the ejb-ref
homeClass - The class object for the desired EJB home
Returns:
The home for the specified EJB (caller needs to cast)
Throws:
javax.resource.ResourceException - thrown if ejbRefName or homeClass is null
Since:
WBI-SF 5.1

invokeJAXRPCCall

public java.lang.Object invokeJAXRPCCall(javax.xml.rpc.Service service,
                                         javax.xml.namespace.QName port,
                                         javax.xml.namespace.QName operation,
                                         javax.xml.namespace.QName returnType,
                                         java.lang.String endpointAddress,
                                         java.lang.Object[] params)
                                  throws javax.resource.ResourceException

This method invokes a web service using JAX-RPC DII APIs. Specify null for the returnType for void operations.

Parameters:
service - The JAX-RPC web service
port - The Qualified Name of the web service port
operation - The Qualified Name of the web service operation
returnType - The Qualified Name of the operation return type
endpointAddress - The end-point address of the web service operation
params - The parameters to the web service operation
Returns:
Object The return value of the web service operation
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with the web service, it is wrapped inside of a JCA ResourceException.
Since:
WBI-SF 5.1

executeWSIFOperation

public org.apache.wsif.WSIFMessage executeWSIFOperation(org.apache.wsif.WSIFService service,
                                                        org.apache.wsif.WSIFMessage message,
                                                        java.lang.String operationName,
                                                        java.lang.String inputName,
                                                        java.lang.String outputName)
                                                 throws javax.resource.ResourceException

This method invokes a web service using WSIF APIs. Note that this method is of short-term benefit to users of WSAD-IE 5.1 (which has nice tooling for generating WSIF interfaces to various kinds of backend systems). In WBI-SF 6.0 it is expected that this method will be deprecated and we'll recommend the use of JService instead.

Parameters:
service - The WSIF web service
message - The WSIF message to be passed to the web service
operationName - The name of the operation on the web service
inputName - Input name for the web service operation
outputName - Output name for the web service operation
Returns:
WSIFMessage The WSIF message returned by the web service
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with the web service, it is wrapped inside of a JCA ResourceException.
Since:
WBI-SF 5.1

invokeJService

public java.lang.Object[] invokeJService(java.lang.String serviceName,
                                         java.lang.String methodName,
                                         java.lang.Object[] input)
                                  throws javax.resource.ResourceException

This method invokes a JService using its DII APIs.

Note that this method throws a javax.resource.NotSupportedException in WBI-SF 5.1. JService support for CMP/A exists but is hidden in the EE ASTk plugin in WSAD-IE 5.1. We plan to make a JService add-on to WBI-SF 5.1 available which will expose this in WSAD-IE and we will provide an updated implementation of this helper interface that does the actual JService invocation (but no changes to the public API; we have separate jar files for the public interface and the private implementation - no change needed to the public jar file or public JavaDoc since this is included here on the interface).

Parameters:
serviceName - The name used to locate the JService
methodName - The name of the method to invoke on the JService
input - Array of objects passed as input to the JService method. (note that this can include DataObject's)
Returns:
Object[] Array of objects returned by the JService method
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with JService, it is wrapped inside a JCA ResourceException.
Since:
WBI-SF 5.1