org.universAAL.middleware.service

Interface ServiceBus

All Known Implementing Classes:

ServiceBusImpl

public interface ServiceBus

The service bus is a call-based bus, i.e., the ServiceCaller members who post a message to this bus normally have a service request and would like to receive a response in return, especially if the service result also includes the provision of specific info. Even if no specific info is expected from the ServiceCallee member, at least a hint about the status of the provision of the service is required, e.g. an acknowledgment stating that the request could be forwarded to an appropriate ServiceCallee, or an error message stating that no appropriate service realization could be found. This interface is available as an OSGi service at the OSGi framework. it is implicitly used by the ServiceCaller-s and ServiceCallee-s that are created within the same OSGi bundle context.

Author:

mtazari - Saied Tazari

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ServiceBus.CallInjector The call injector allows to directly call a service with a ServiceCall.

Field Summary

Fields

Modifier and Type	Field and Description
static String	LOG_MATCHING_END
static String	LOG_MATCHING_MISMATCH
static String	LOG_MATCHING_MISMATCH_CODE
static String	LOG_MATCHING_MISMATCH_DETAILS
static String	LOG_MATCHING_NOSUCCESS
static String	LOG_MATCHING_PROFILE
static String	LOG_MATCHING_PROFILES_END
static String	LOG_MATCHING_PROVIDER_END
static String	LOG_MATCHING_START
static String	LOG_MATCHING_SUCCESS

Method Summary

Modifier and Type	Method and Description
void	addAvailabilitySubscription(String callerID, AvailabilitySubscriber subscriber, ServiceRequest request) Adds an availability subscription, in other words a listener, to receive events about the availability of services matching the given request.
void	addNewServiceProfiles(String calleeID, ServiceProfile[] realizedServices, boolean throwOnDuplicateReg) Registers (advertises) new services (by providing descriptions of them) that will be provided by the ServiceCallee with the specified ID.
void	brokerReply(String calleeID, BusMessage response) Can be used by ServiceCallees to send a response to the bus which will be delivered to the caller who initiated the initial request.
void	brokerRequest(String callerID, BusMessage request) Can be used by ServiceCallers to send a request to the bus.
ServiceProfile[]	getAllServices(String callerID) A method used to retrieve the descriptions of all services advertised on the service bus.
HashMap<String,List<ServiceProfile>>	getMatchingServices(String serviceClassURI) Get all service profiles that describe services of the given service class.
ServiceProfile[]	getMatchingServices(String callerID, Service template) Get all service profiles that describe services that match the given template in terms of "query by example".
ServiceProfile[]	getMatchingServices(String callerID, String serviceClassURI) Get all service profiles that describe services of the given service class.
ServiceProfile[]	getMatchingServices(String callerID, String[] keywords) This version of the method accepts simple keyword-based queries about registered services.
void	removeAvailabilitySubscription(String callerID, AvailabilitySubscriber subscriber, String requestURI) Removes an availability subscription from the bus, which was previously added using addAvailabilitySubscription method.
void	removeMatchingProfiles(String calleeID, ServiceProfile[] realizedServices) Removes specified service profiles that were previously registered by the ServiceCalee with the specified ID.
void	unregister(String calleeID, ServiceCallee callee) Unregisters a service callee from the bus.
void	unregister(String callerID, ServiceCaller caller) Unregisters a service caller from the bus.

Field Detail

LOG_MATCHING_START

static final String LOG_MATCHING_START

See Also:

Constant Field Values

LOG_MATCHING_PROFILE

static final String LOG_MATCHING_PROFILE

See Also:

Constant Field Values

LOG_MATCHING_SUCCESS

static final String LOG_MATCHING_SUCCESS

See Also:

Constant Field Values

LOG_MATCHING_NOSUCCESS

static final String LOG_MATCHING_NOSUCCESS

See Also:

Constant Field Values

LOG_MATCHING_PROFILES_END

static final String LOG_MATCHING_PROFILES_END

See Also:

Constant Field Values

LOG_MATCHING_PROVIDER_END

static final String LOG_MATCHING_PROVIDER_END

See Also:

Constant Field Values

LOG_MATCHING_END

static final String LOG_MATCHING_END

See Also:

Constant Field Values

LOG_MATCHING_MISMATCH

static final String LOG_MATCHING_MISMATCH

See Also:

Constant Field Values

LOG_MATCHING_MISMATCH_CODE

static final String LOG_MATCHING_MISMATCH_CODE

See Also:

Constant Field Values

LOG_MATCHING_MISMATCH_DETAILS

static final String LOG_MATCHING_MISMATCH_DETAILS

See Also:

Constant Field Values

Method Detail

addAvailabilitySubscription

void addAvailabilitySubscription(String callerID,
                                 AvailabilitySubscriber subscriber,
                                 ServiceRequest request)

Adds an availability subscription, in other words a listener, to receive events about the availability of services matching the given request.

Parameters:

callerID - the ID of the caller that is registering a subscriber.

subscriber - the object which will be notified when matching services are advertised or removed from the service bus.

request - the request to which newly registered or unregistered services must match in order to notify the subscriber about the corresponding events.

addNewServiceProfiles

void addNewServiceProfiles(String calleeID,
                           ServiceProfile[] realizedServices,
                           boolean throwOnDuplicateReg)

Registers (advertises) new services (by providing descriptions of them) that will be provided by the ServiceCallee with the specified ID.

Parameters:

calleeID - the ID of the ServiceCallee that is advertising new services on the service bus.

realizedServices - the description of the new services in terms of an array of service profiles.

throwOnDuplicateReg - Specifies whether this method should throw an exception or just ignore it when a profile is registered with a process URI that is already registered.

Throws:

ProfileExistsException - if one of the profiles exists already. In that case, none of the profiles will be registered.

getAllServices

ServiceProfile[] getAllServices(String callerID)

A method used to retrieve the descriptions of all services advertised on the service bus.

Parameters:

callerID - the ID of the caller that is asking the service bus.

Returns:

descriptions of all registered services in terms of an array of service profiles.

getMatchingServices

ServiceProfile[] getMatchingServices(String callerID,
                                     Service template)

Get all service profiles that describe services that match the given template in terms of "query by example". This version of the method makes it possible to make more specific queries by specifying restrictions for certain properties of services.

Parameters:

callerID - the ID of the caller that is asking the service bus.

template - the template to be used for making a "query by example"..

Returns:

profiles of services registered with the service bus that match the given template, or null if no such service has been registered.

getMatchingServices

ServiceProfile[] getMatchingServices(String callerID,
                                     String serviceClassURI)

Get all service profiles that describe services of the given service class. This version of the method makes it easier to make a simple query of all instances of a named service class by specifying its URI.

Parameters:

callerID - the ID of the caller that is asking the service bus.

serviceClassURI - the URI of the desired service class.

Returns:

profiles of services registered with the service bus that are instances of the given service class, or null if no such service has been registered.

getMatchingServices

ServiceProfile[] getMatchingServices(String callerID,
                                     String[] keywords)

This version of the method accepts simple keyword-based queries about registered services. The given keywords are checked against all names and textual descriptions used in the service profiles. A match is there only if all the given keywords have at least one occurrence.

Parameters:

callerID - the ID of the caller that is asking the service bus.

keywords - the set of keywords to be used for textual match.

Returns:

the profiles of the matched services, or null if no such service is available.

removeAvailabilitySubscription

void removeAvailabilitySubscription(String callerID,
                                    AvailabilitySubscriber subscriber,
                                    String requestURI)

Removes an availability subscription from the bus, which was previously added using addAvailabilitySubscription method.

Parameters:

callerID - the ID of the caller that owns the listener

subscriber - the listeners registered by the caller

requestURI - the URI of the request used previously for subscription

removeMatchingProfiles

void removeMatchingProfiles(String calleeID,
                            ServiceProfile[] realizedServices)

Removes specified service profiles that were previously registered by the ServiceCalee with the specified ID.

Parameters:

calleeID - the ID of the ServiceCalee that owns the service profiles.

realizedServices - the service profiles to be removed.

brokerRequest

void brokerRequest(String callerID,
                   BusMessage request)

Can be used by ServiceCallers to send a request to the bus. The bus will then try to find matching services using the set of registered service profiles; for each match, the provider ServiceCallee will be asked by the bus to invoke the corresponding service utility and inform the bus about the results by calling brokerReply(String, BusMessage). The bus will then inform the original requester (the ServiceCaller that has called this method) about the result.

Parameters:

callerID - the ID of the caller that is sending the request.

request - the actual request message.

brokerReply

void brokerReply(String calleeID,
                 BusMessage response)

Can be used by ServiceCallees to send a response to the bus which will be delivered to the caller who initiated the initial request.

Parameters:

calleeID - the ID of the service callee which processed the request.

response - the actual response message.

unregister

void unregister(String callerID,
                ServiceCaller caller)

Unregisters a service caller from the bus.

Parameters:

callerID - the ID of the caller to be unregistered.

caller - the ServiceCaller object to be unregistered.

unregister

void unregister(String calleeID,
                ServiceCallee callee)

Unregisters a service callee from the bus.

Parameters:

calleeID - the ID of the callee to be unregistered.

callee - the ServiceCallee object to be unregistered.

getMatchingServices

HashMap<String,List<ServiceProfile>> getMatchingServices(String serviceClassURI)

Get all service profiles that describe services of the given service class. This version of the method makes it easier to make a simple query of all instances of a named service class by specifying its URI.

Parameters:

serviceClassURI - the URI of the desired service class.

Returns:

Map containing as a key calleeID which registered ServiceProfiles in the service bus that are instances of the given service class. Returned profiles are stored in value part of map in a List.