ch.ethz.iks.r_osgi
Interface RemoteOSGiService

public interface RemoteOSGiService

RemoteOSGiService provides transparent access to services on remote service platforms. It uses SLP as underlying discovery protocol. Local services can be registered for remoting, applications can register listeners for ServiceTypes to be informed whenever matching services have been discovered.

As soon as a service has been discovered and the listener has been informed, the application can fetch the service. In the default case, the service interface is transferred to the receiving peer together with an optional smart proxy class and optional injections. The service then builds a proxy bundle and registers it with the local framework so that the application can get a service reference as if the service was local. Internally, all methods of the service interface are implemented as remote method calls.

Services can define smart proxies to move some parts of the code to the client. This is done by an abstract class. All implemented method will be executed on the client, abstract methods will be implemented by remote method calls. Moving parts of the code to the client can be useful for saving service provider platform's resources.

Injections are used if the service interface uses classes as method arguments that are not expected to be present on client side. These classes will be automatically injected into the proxy bundle. The registrator can manually inject additional classes.

With version 0.5, there is also the possibility to register a service with the MIGRATE_BUNDLE policy. In this case, the bundle that provides the service is moved to the requesting peer.

Since:

0.1

Author:

Jan S. Rellermeyer, ETH Zurich

Field Summary

static String	INJECTIONS For special purposes, the service can decide to inject other classes into the proxy bundle that is dynamically created on the client side.
static String	PRESENTATION property for registration of a service UI component that gived the user a presentation of the service.
static String	R_OSGi_REGISTRATION this property has to be set in order to release a service for remote access.
static String	SERVICE_PROXY_POLICY Deprecated. With the new model, service proxies is the only supported policy. Any value set to the R_OSGi_REGISTRATION policy will have the effect of SERVICE_PROXY_POLICY;
static String	SERVICE_URI the property key for the host name of the remote service.
static String	SMART_PROXY Can be set to use a smart proxy.

Method Summary

RemoteServiceReference[]	connect(URI endpoint) connect to a remote OSGi framework.
void	disconnect(URI endpoint) disconnect from a connected host.
ChannelEndpointManager	getEndpointManager(URI remoteEndpointAddress) get the endpoint manager for a channel to a given remote peer.
Object	getRemoteService(RemoteServiceReference ref) get the a remote service.
RemoteServiceReference	getRemoteServiceReference(URI serviceURI) get a remote service reference for a given URI.
RemoteServiceReference[]	getRemoteServiceReferences(URI endpointAddress, String clazz, Filter filter) get remote service references for all services on a certain peer that match the given criteria.
void	ungetRemoteService(RemoteServiceReference remoteServiceReference) unget the service.

Field Detail

R_OSGi_REGISTRATION

static final String R_OSGi_REGISTRATION

this property has to be set in order to release a service for remote access. Currently, the following two policies are supported.

Since:

0.5

See Also:

Constant Field Values

SERVICE_PROXY_POLICY

static final String SERVICE_PROXY_POLICY

Deprecated. With the new model, service proxies is the only supported policy. Any value set to the R_OSGi_REGISTRATION policy will have the effect of SERVICE_PROXY_POLICY;

policy "service_proxy" means: dynamically build a proxy at client side. (default)

Since:

0.5

See Also:

Constant Field Values

SMART_PROXY

static final String SMART_PROXY

Can be set to use a smart proxy. Smart proxies have to be abstract classes implementing the service interface. All abstract methods are implemented as remote calls, implemented methods remain untouched. This allows to perform some of the work on client side (inside of implemented methods). The value of this property in the service property dictionary has to be a the name of a class.

Since:

0.5

See Also:

Constant Field Values

INJECTIONS

static final String INJECTIONS

For special purposes, the service can decide to inject other classes into the proxy bundle that is dynamically created on the client side. For instance, if types are use as arguments of method calls that are not part of the standard execution environment and the service does not want to rely on assumption that the corresponding classes are present on client side, it can inject these classes. The value of this property in the service property dictionary has to be an array of Class objects.

Since:

0.5

See Also:

Constant Field Values

PRESENTATION

static final String PRESENTATION

property for registration of a service UI component that gived the user a presentation of the service. The value of the property in the service property dictionary has to be a name of a class implementing org.service.proposition.remote.ServiceUIComponent. When this property is set, the presentation is injected into the bundle and the R-OSGi ServiceUI can display the presentation when the service is discovered.

Since:

0.5

See Also:

Constant Field Values

SERVICE_URI

static final String SERVICE_URI

the property key for the host name of the remote service. This constant is set by R-OSGi when a service is transferred to a remote peer. So to find out whether a service is provided by an R-OSGi proxy, check for the presence of this key in the service properties.

Since:

1.0

See Also:

Constant Field Values

Method Detail

connect

RemoteServiceReference[] connect(URI endpoint)
                                 throws RemoteOSGiException

connect to a remote OSGi framework. Has to be called prior to any service access. Causes the frameworks to exchange leases and start the transport of remote events.

Parameters:

endpoint - the endpoint to connect to.

Returns:

the array of remote service references of the services that the remote frameworks offers.

Throws:

RemoteOSGiException - in case of connection errors.

Since:

0.6

disconnect

void disconnect(URI endpoint)
                throws RemoteOSGiException

disconnect from a connected host.

Parameters:

endpoint - the URI of the remote host.

Throws:

RemoteOSGiException - if something goes wrong.

getRemoteServiceReference

RemoteServiceReference getRemoteServiceReference(URI serviceURI)

get a remote service reference for a given URI.

Parameters:

serviceURI - the uri of the service. Has to be a channel URI including a fragment, which is the service ID on the other peer.

Returns:

the remote service reference, or null, if the service is not present.

getRemoteServiceReferences

RemoteServiceReference[] getRemoteServiceReferences(URI endpointAddress,
                                                    String clazz,
                                                    Filter filter)

get remote service references for all services on a certain peer that match the given criteria.

Parameters:

endpointAddress - the URI of the peer.

clazz - a service interface class, or null for all services.

filter - a filter string, or null

Returns:

an array of remote service references, or null if no services match.

getRemoteService

Object getRemoteService(RemoteServiceReference ref)

get the a remote service. If there is no proxy bundle for the service so far, it is generated.

Parameters:

ref - the remote service reference.

Returns:

the service belonging to the service url or null, if no such service is present.

ungetRemoteService

void ungetRemoteService(RemoteServiceReference remoteServiceReference)

unget the service. The proxy bundle will be uninstalled. The service will be no longer available, unless it is retrieved through getRemoteService(RemoteServiceReference) again.

Parameters:

remoteServiceReference - thre remote service reference.

getEndpointManager

ChannelEndpointManager getEndpointManager(URI remoteEndpointAddress)

get the endpoint manager for a channel to a given remote peer.

Parameters:

remoteEndpointAddress - the endpoint address of the remote peer.

Returns:

the endpoint manager, or null if no such channel exists.