Index Changes
Page Difference

Difference between version and version     

Back to Fuji Service API, or Fuji Service API Info


At line 15 removed 1 line.
!! Consuming Services
At line 17 removed 116 lines.
Consuming a service using the Service API consists of the following:
* Obtaining a ServiceConsumer reference by querying the OSGi service registry directly or using annotation-based injection
* Creating a message and populating it with content (properties, payload, etc.)
* Invoking the service with the message and digesting the response (if applicable)
[{Image src='service-api-consumer.jpg' width='50%' align='left'}]
!
A ServiceConsumer instance is identified via two properties: service name and endpoint name. These can be specified as annotation properties or as properties associated with a query in the OSGi service registry. The Fuji runtime automatically registers a ServiceConsumer instance in the registry for each service endpoint activated on the NMR.
\\ \\
Invoking a service via the ServiceConsumer interface takes two forms:
* ''send'' : represents a one-way invocation of a service; results in an InOnly message exchange over the NMR.
* ''call'' : represents a request-response invocation of a service; results in an InOut message exchange over the NMR.
Both calls are synchronous. The ''send'' method waits for a DONE/ERROR before returning. The ''call'' method waits for a response message/fault before returning.
\\ \\
''NOTE: We can consider an asynchronous mechanism which would require a callback handler in the client''
\\ \\
!! Providing Services
Providing a service using the Service API can take one of two forms:
!''Java Interface''
* Implement the ServiceProvider interface
* Register an instance of the ServiceProvider implementation in the OSGi service registry
* Process messages received via the invoke() method and optionally return a response
!''Annotation''
* Annotate with a service provider annotation
* Each public method in the class becomes an invokable service operation
* Process messages received via public methods and optionally return a response
[{Image src='service-api-provider.jpg' width='50%' align='left'}]
!
The following properties are required for instances of a service provider:
* Service name : defaults to class name, can be specified using:
** annotation property
** implementation of getServiceName()
* Endpoint name : defaults to hashCode of object instance, can be specified using:
** annotation property
** implementation of getEndpointName()
* Operation names : defaults to method name, can be specified using:
** annotation
** implementation of getOperationNames()
All invocations are synchronous, whether the provider implements ServiceProvider or uses annotations.
\\ \\
!! Message Processing
The Service API provides some additional facilities for message processing beyond the standard NormalizedMessage abstraction available in JBI. That said, all aspects of the standard NormalizedMessage are still available (e.g. attachments, properties). The ServiceMessage class in the Service API provides the following additional features:
* Automatic wrapping and unwrapping of WSDL 1.1 messages to retain interoperability with JBI components. This allows clients of the Service API to focus on the message payload without worrying about WSDL vagaries.
* Support for arbitrary object payloads. The setPayload() and getPayload() methods on ServiceMessage accept and return generics representing any object type. Objects used as message payloads must be part of an exported package in the OSGi runtime. Care should be taken when using this facility with JBI components, as most will expect XML-based messages for interoperability.
\\
!! API Details
! Annotations
__@Consumer__ \\
Used for field-level injection of ServiceConsumer references.
* service : service name
* endpoint : endpoint name
\\
__@Provider__ \\
Specified at the class level to extract a ServiceProvider instance from a class.
* name ''(optional)'' : service name
* endpoint ''(optional)'' : endpoint name
\\
__@Operation__ \\
Specified at the method level. Allows a class to change metadata associated with a service operation.
* name : operation name - serves as an override in place of the method name
\\
__@MessageFactory__ \\
Used for field-level injection of ServiceMessageFactory references. Can only be used in classes with @Consumer or @Provider annotations.
\\ \\
! Java Interfaces
{{{
public interface ServiceProvider {
ServiceMessage invoke(ServiceMessage message) throws Exception;
void setMessageFactory(ServiceMessageFactory factory);
}
}}}
\\
{{{
public interface ServiceConsumer {
public ServiceMessage call(String operation, ServiceMessage request) throws Exception;
public void send(String operation, ServiceMessage request) throws Exception;
public ServiceMessageFactory getServiceMessageFactory();
}
}}}
\\
{{{
public interface ServiceMessage<T> extends NormalizedMessage {
public void setPayload(T payload) throws Exception;
public T getPayload() throws Exception;
}
}}}
\\
{{{
public interface ServiceMessageFactory {
<T> ServiceMessage<T> createMessage(T payload);
}
}}}
\\ \\
!! Deployment Choices
The Service API can be used by and code deployed on the Fuji platform. A few examples:
* OSGi bundles
* Java objects deployed to the POJO Service Engine
* Webapps deployed in GlassFish v3
* JRuby scripts deployed to the JRuby Service Engine
One of the design goals of the Service API is to be 100% compatible with the POJO Service Engine. Hopefully, the same set of annotations can be shared between the Service API and the POJO SE, with the POJO SE likely offering a superset of functionality (e.g. threading config).
G'day, Anonymous Guest

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-30) was last changed on 17-Feb-09 17:08 PM, -0800 by MarkWhite