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 java.lang.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 java.lang.String	PRESENTATION property for registration of a service UI component that gived the user a presentation of the service.
static java.lang.String	R_OSGi_REGISTRATION this property has to be set in order to release a service for remote access.
static java.lang.String	SERVICE_URI the property key for the host name of the remote service.
static java.lang.String	SMART_PROXY Can be set to use a smart proxy.

Method Summary

void	asyncRemoteCall(URI service, java.lang.String methodSignature, java.lang.Object[] args, AsyncRemoteCallCallback callback) make an asynchronous remote call to a service
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.
int	getListeningPort(java.lang.String protocol) get the port on which the corresponding NetworkChannelFactory for the given protocol listens for incoming connections.
java.lang.Object	getRemoteService(RemoteServiceReference ref) get the a remote service.
java.lang.Object	getRemoteServiceBundle(RemoteServiceReference ref, int timeout) get a copy of the bundle that has registered the remote service.
RemoteServiceReference	getRemoteServiceReference(URI serviceURI) get a remote service reference for a given URI.
RemoteServiceReference[]	getRemoteServiceReferences(URI endpointAddress, java.lang.String clazz, org.osgi.framework.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 java.lang.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

SMART_PROXY

static final java.lang.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 java.lang.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 java.lang.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 java.lang.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,
                                        java.io.IOException

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.

ConnectException - if the connection attempt fails.

java.io.IOException

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,
                                                    java.lang.String clazz,
                                                    org.osgi.framework.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

java.lang.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.

getRemoteServiceBundle

java.lang.Object getRemoteServiceBundle(RemoteServiceReference ref,
                                        int timeout)
                                        throws java.lang.InterruptedException

get a copy of the bundle that has registered the remote service.

Parameters:

ref - the remote service reference

timeout - number of milliseconds to wait for the service to be registered after the bundle has been started. A value of 0 means indefinite time, a negative value means don't wait at all.

Returns:

the service object or null if the timeout is exceeded and the service has not appeared.

Throws:

java.lang.InterruptedException

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.

asyncRemoteCall

void asyncRemoteCall(URI service,
                     java.lang.String methodSignature,
                     java.lang.Object[] args,
                     AsyncRemoteCallCallback callback)

make an asynchronous remote call to a service

Parameters:

service - the URI of the service

methodSignature - the signature of the method to call

args - the arguments to pass

callback - a callback to be called when the result is available

getListeningPort

int getListeningPort(java.lang.String protocol)

get the port on which the corresponding NetworkChannelFactory for the given protocol listens for incoming connections.

Parameters:

protocol - the protocol identifier string. E.g., "r-osgi" for the default TCP-based transport

Returns:

the port number or -1 if the protocol is not supported.