IBM WebSphere Application ServerTM
Release 7

com.ibm.wbiserver.cmpa
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 <beanName>UserDefinedPushDownMethods classes. This sub-interface adds procedural-specific helpers beyond the generic helpers available in the super-interface.

Since:
WBI-SF 5.1

Field Summary
static java.lang.String COPYRIGHT
           
 
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).
 DataObject createSDO(java.lang.String serviceName, java.lang.String methodName)
          This method creates a Service Data Object, to be used as input to an SCA Service method by CMP/A beans based on SCA.
 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)
          Deprecated. Use invokeJAXRPCCall or invokeSCAService instead
 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 invokeSCAService(java.lang.String serviceName, java.lang.String methodName, java.lang.Object input)
          This method invokes an SCA Service synchronously using its DII APIs.
 void registerJAXRPCTypeMapping(javax.xml.rpc.Service service, javax.xml.namespace.QName xmlType, java.lang.Class javaType)
          Registers custom types with the WebSphere JAX-RPC runtime.
 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.wbiserver.cmpa.WSPushDownHelper
createCCIIndexedRecord, createCCIRecord, createResourceException, createResourceException, returnCCIIndexedRecord
 

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT
See Also:
Constant Field Values
Method Detail

createCCIMappedRecord

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

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

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

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

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
spec - A CCI InteractionSpec, populated with the information needed by the desired backend
input - A CCI record passed as input to the JCA interaction
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

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

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

registerJAXRPCTypeMapping

void registerJAXRPCTypeMapping(javax.xml.rpc.Service service,
                               javax.xml.namespace.QName xmlType,
                               java.lang.Class javaType)
                               throws javax.resource.ResourceException

Registers custom types with the WebSphere JAX-RPC runtime. All customer-defined types passed as parameters, expected as return values, or raised as exceptions by any of the web service operations used in any push-down methods of a JAX-RPC DII-based CMP/A bean should be registered via this API.

This API performs similar type mapping initialization as what would appear in the initTypeMapping of the IBM-generated SOAP binding stub for the web service. Customers using the static generated stub to invoke the web service do not need to call this API, whereas those using the Dynamic Invocation Interface (DII) to the web service do. Note that this method is not supported in a managed environment (where the Service was obtained via a java:comp lookup); in that case, an UnsupportedOperationException will be contained in the ResourceException thrown to the caller. See chapter 15 of the JAX-RPC 1.1 specification for further details.

Parameters:
service - The JAX-RPC web service
xmlType - The Qualified Name of the type being registered
javaType - The Java Class of the type being registered
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with the web service, it is wrapped inside of a JCA ResourceException.
Since:
WBI 6.0

executeWSIFOperation

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
Deprecated. Use invokeJAXRPCCall or invokeSCAService instead

This method invokes a web service using WSIF APIs.

Note that this method was primarily for users of WSAD-IE 5.1 (which had nice tooling for generating WSIF interfaces to various kinds of backend systems). WSIF has been deprecated in WebSphere 6.0, in favor of either JAX-RPC or SCA.

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

invokeSCAService

java.lang.Object invokeSCAService(java.lang.String serviceName,
                                  java.lang.String methodName,
                                  java.lang.Object input)
                                  throws javax.resource.ResourceException

This method invokes an SCA Service synchronously using its DII APIs. This version of the method expects an Object as input and returns an Object as output. Note that the input and output Objects can be SDOs, such as when the SCA Service represents a document/literal wrapped WSDL or a Java interface where the method takes multiple arguments.

Parameters:
serviceName - The name used to locate the SCA Service, as specified in the SCA .references file for this EJB jar
methodName - The name of the method to invoke on the SCA Service
input - The input to the SCA Service method
Returns:
Object The object returned by the SCA Service method
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with the SCA Service, it is wrapped inside of a JCA ResourceException.
Since:
WBI 6.0

createSDO

DataObject createSDO(java.lang.String serviceName,
                     java.lang.String methodName)
                     throws javax.resource.ResourceException

This method creates a Service Data Object, to be used as input to an SCA Service method by CMP/A beans based on SCA.

Parameters:
serviceName - The name used to locate the SCA Service, as specified in the SCA .references file for this EJB jar
methodName - The name of the method of the SCA Service for which this SDO will be the input
Returns:
DataObject The requested Service Data Object
Throws:
javax.resource.ResourceException - If any exception is encountered interacting with the SCA runtime, it is wrapped inside of a JCA ResourceException.
Since:
WBI 6.0

IBM WebSphere Application ServerTM
Release 7