Amdatu Remote
Project Info
| Tools | Location |
|---|---|
| Source Code | https://bitbucket.org/amdatu/amdatu-remoteservices |
| Issue Tracking | https://amdatu.atlassian.net/browse/AMDATURS |
| Continuous Build | https://amdatu.atlassian.net/builds/browse/AMDATURS |
Software Design
Amdatu Remote provides component implementations along the lines of the roles and entities as defined by the Remote Service Admin specification (see Figure 122.1) . Every bundle provides a single discovery, topology manager of remote service admin service implementation. This means different components can be mixed and matched as required ( image source: Figure 122.1; OSGi Enterprise Release 5).
Discovery Components
Discovery components are responsible for publishing exportable as well as discovering importable service endpoints across frameworks. All specification mandated interaction between discovery components and topology manager is based on the exchange of EndpointDescription instances across EndpointListener and EndpointEventListener service interfaces.
HTTP endpoint discovery (Configured)
| Bundle | org.amdatu.remote.discovery.configured/0.1.0 | ||||||||||||||
| Description | OSGi RSA 1.1 discovery implementation that uses (pre)configured HTTP endpoints that provide the actual service discovery based on HTTP/XML (using the extender format as defined in the RSA specification). | ||||||||||||||
| Capability |
| ||||||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
HTTP endpoint discovery (ZooKeeper)
| Bundle | org.amdatu.remote.discovery.zookeeper/unreleased | ||||||||||||||||||
| Description | OSGi RSA 1.1 Discovery implementation that uses a ZooKeeper backend to discover HTTP endpoints that provide the actual service discovery based on HTTP/XML (using the extender format). | ||||||||||||||||||
| Capability |
| ||||||||||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
HTTP endpoint discovery (Etcd)
| Bundle | org.amdatu.remote.discovery.etcd/unreleased | ||||||||||||||||
| Description | OSGi RSA 1.1 Discovery implementation that uses an Etcd backend to discover HTTP endpoints that in provide the actual service discovery based on HTTP/XML (using the extender format). | ||||||||||||||||
| Capability |
| ||||||||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
HTTP endpoint discovery (Bonjour)
| Bundle | org.amdatu.remote.discovery.bonjour/0.1.0 | ||||||||||||
| Description | OSGi RSA 1.1 Discovery implementation that uses Bonjour for discovering HTTP endpoints that in turn provide the actual service discovery based on HTTP/XML (using the extender format). The Bonjour discovery uses JmDNS. | ||||||||||||
| Capability |
| ||||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
HTTP endpoint discovery (SLP)
| Bundle | org.amdatu.remote.discovery.slp/0.1.0 | ||||||||||||
| Description | OSGi RSA 1.1 Discovery implementation that uses SLP for discovering HTTP endpoints that in turn provide the actual service discovery based on HTTP/XML (using the extender format). The SLP discovery uses LiveTribe-SLP. Notes:
| ||||||||||||
| Capability |
| ||||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
Local Discovery Extender
| Bundle | org.amdatu.remote.discovery.extender/0.1.0 |
| Description | OSGi RSA 1.1 Discovery implementation that provides the osgi.extender capability that allows bundles to provide endpoint descriptions through XML files. |
| Capability |
|
| Configuration | The service does not provide or need any configuration. |
Topology Manager Components
Topology Managers are, based on locally registered services and remotely discovered services, responsible for controlling the imports and exports of services using registered RemoteServiceAdmin services to do so. All interaction with discovery components is based on the exchange of EndpointDescription instances across EndpointListener and EndpointEventListener service interfaces.
Promiscuous Topology
| Bundle | org.amdatu.remote.topology.promiscuous/0.1.0 | ||||
| Description | OSGi RSA 1.1 Topology Manager implementation of a that implements a promiscuous policy. This policy basically exports any exportable service that matches an exports filter and imports any importable service that matches another imports filter. | ||||
| Capability |
| ||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
Remote Service Admin Components
Remote Service Admin components are passive components that register as RemoteServiceAdmin services and are actually capable of importing and exporting certain services as defined by configuration type and constraint by intents. Interested parties may register themselves as RemoteServiceAdminListener to be able to receive import/export events as they occur.
Admin HTTP/Json
| Bundle | org.amdatu.remote.admin.http/0.1.1 | ||||||||||
| Description | OSGi Remote Service Admin 1.1 implementation that implements the "org.amdatu.remote.admin.http" configuration type using HTTP transport. The remote service invocation uses a JSON representation that holds the method signature ("m") and the arguments array ("a"). Sample request ===>
POST /endpoint HTTP/1.1
Host: localhost
{
"m":"foo(Ljava/lang/String;)I;" # Signature is <methodname>([ <argumenttype> ])<returntype> using VM type encoding.
"a":[ "Hello World" ] # Array of arguments (JSON values)
}
<=== return value
HTTP/1.1 200 OK
{ "r":"hello world"} # Return value (JSON value)
<=== null return
HTTP/1.1 200 OK
{ "r":null}
<=== void return
HTTP/1.1 200 OK
{}
<=== exception
HTTP/1.1 200 OK
{"e":{"type":"java.lang.IllegalArgumentException","msg":"Invalid value!","stacktrace":[]}}
<=== request issue
HTTP/1.1 4xx
<=== server issue
HTTP/1.1 5xx
Be aware that this implementation currently supports primitive types, most of the collection types supported by Java (Lists, Sets and Maps) as well as "simple" POJOs having a default constructor and public getters and setters. There is limited support for dealing with exceptions thrown in remote services: the exception type itself has to be available at the calling side. | ||||||||||
| Capability | osgi.remoteserviceadmin.distribution; configs:List<String>="org.amdatu.remote.admin.http"; version:Version="1.1" | ||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
Admin HTTP/Avro
| Bundle | org.amdatu.remote.admin.http.avro/0.1.0 (unreleased) | ||||||||||
| Description | OSGi Remote Service Admin 1.1 implementation that implements the "org.amdatu.remote.admin.http.avro" configuration type using HTTP transport. The remote service invocation uses Apache Avro based serialization | ||||||||||
| Capability | osgi.remoteserviceadmin.distribution; configs:List<String>="org.amdatu.remote.admin.http.avro"; version:Version="1.1" | ||||||||||
| Configuration | The service can both be configured using OSGi environment properties and using Configuration Admin. In case both methods are used the latter takes precedence. The service PID for this service is
|
Component Deployment
Deployment of Amdatu Remote follows the selection of the implementing bundles of the desired components. By design (and specification) multiple components, and thus bundles, of each role may be deployed. However a minimal deployment involves at least one of each. This is shown in the deployment diagram below, that also illustrates the implicit requirement importing and exporting parties require a shared service api to be deployed.
Getting Started
Because OSGi Remote Service cleanly hooks into the existing service registry, developing applications that can works with Remote Services should be no problem for anyone familiar with OSGi development. As long as the service interface represent stateless contracts with pass-by-value intent there is nothing to worry about. Below a simple example taken from the demo project that can be found in the source repository
Implementing a simple chat client
A simple chat client implements two simple interfaces for message exchange. In this code there is nothing specific to Remote Services!
public interface MessageReceiver {
void receive(String sender, String message);
}
public interface MessageSender {
void send(String message);
}
public class ChatClient implements MessageSender, MessageReceiver {
...
}
The activator marks the receiver interface as an exported interface. This specifies that the service may be exported using that interface.
@Override
public void init(BundleContext context, DependencyManager manager) throws Exception {
Dictionary<String, Object> props = new Hashtable<String, Object>();
props.put(RemoteConstants.SERVICE_EXPORTED_INTERFACES, MessageReceiver.class.getName());
manager.add(createComponent()
.setInterface(new String[] { MessageSender.class.getName(), MessageReceiver.class.getName() }, props)
.setImplementation(ChatClient.class)
.add(createServiceDependency()
.setService(MessageReceiver.class)
.setRequired(false)
.setCallbacks("addReceiver", "removeReceiver")
));
}
Thats all folks! Multiple instances of the ChatClient, deployed into different containers, can now see and invoke each other's receivers.
Deploying the simple chat client
Deployment is no different from any other OSGi application. Simply deploy the Amdatu Remote components and their requirements along with the remotable services. The example below is taken from the Chat Demo bnd run file found in the source repository.
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (4.2.1)
1|Active | 1|org.osgi.service.remoteserviceadmin (6.0.0.201403170857)
2|Active | 1|osgi.enterprise (5.0.0.201203141834)
3|Active | 1|Apache Felix Configuration Admin Service (1.8.0)
4|Active | 1|Apache Felix Dependency Manager (3.1.0)
5|Active | 1|Apache Felix Dependency Manager Shell (3.0.1)
6|Active | 1|Apache Felix Gogo Command (0.12.0)
7|Active | 1|Apache Felix Gogo Runtime (0.10.0)
8|Active | 1|Apache Felix Gogo Shell (0.10.0)
9|Active | 1|Apache Felix Http Jetty (2.2.2)
10|Active | 1|Apache Felix Log Service (1.0.1)
11|Active | 1|Apache Felix Metatype Service (1.0.6)
12|Active | 1|Amdatu Remote - Discovery (Bonjour) (0.1.1)
13|Active | 1|Amdatu Remote - Remote Service Admin (HTTP) (0.1.1)
14|Active | 1|Amdatu Remote - Topology Manager (Promiscuous) (0.1.1)
15|Active | 1|Amdatu Remote - Chat Demo api (0.1.0)
16|Active | 1|Amdatu Remote - Chat Demo impl (0.1.0)