org.universAAL.middleware.service

Class ServiceCaller

java.lang.Object

org.universAAL.middleware.bus.member.BusMember

org.universAAL.middleware.bus.member.Caller

org.universAAL.middleware.service.ServiceCaller

Direct Known Subclasses:

CallerWrapper, CHECaller, CHECaller, DefaultServiceCaller, DMServiceCaller, ProxySCaller, SCaller

public abstract class ServiceCaller
extends Caller

/** This is an abstract class that the service caller members of the service bus must derive from. Any ServiceCaller must incorporate the logic of handling service responses into the implementation of the abstract method handleResponse(String, ServiceResponse).

Author:

mtazari - Saied Tazari, Carsten Stockloew

Field Summary

Fields inherited from class org.universAAL.middleware.bus.member.BusMember

busResourceURI, owner, theBus

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ServiceCaller(ModuleContext context) The default constructor for this class.

Method Summary

Modifier and Type	Method and Description
void	addAvailabilitySubscription(AvailabilitySubscriber subscriber, ServiceRequest request) Adds an availability subscription, in other words a listener, to receive events about the availability of a specified service.
void	busDyingOut(AbstractBus b) This method is called when the bus is stopped to announce this to the bus members.
ServiceResponse	call(ServiceRequest request) The "normal" (synchronous) way of calling a service.
ServiceResponse	call(String request) This method is a way of calling a service using Turtle Strings as input.
abstract void	communicationChannelBroken() This abstract method is called for each member of the bus when the bus is being stopped.
ServiceProfile[]	getAllServices() A method used to instantly retrieve all services available to this caller.
ServiceProfile[]	getMatchingService(Service s) A method used to retrieve a specified service, available to this ServiceCaller.
ServiceProfile[]	getMatchingService(String serviceClassURI) A method used to retrieve a specified service, available to this ServiceCaller.
ServiceProfile[]	getMatchingService(String[] keywords) A method used to retrieve a service available to this caller, that matches the specified keywords.
String	getMyID()
void	handleReply(BusMessage m)
abstract void	handleResponse(String reqID, ServiceResponse response) Will be called automatically in a new thread whenever the response corresponding to a previous call to sendRequest(ServiceRequest) is ready.
ServiceResponse	inject(ServiceCall call, PeerCard receiver) Can be used to inject a ServiceCall to the bus.
ServiceResponse	inject(ServiceCall call, String receiver) Can be used to inject a ServiceCall to the bus.
void	removeAvailabilitySubscription(AvailabilitySubscriber subscriber, String requestURI) Removes an availability subscription for this Caller, which was previously added using addAvailabilitySubscription method.
String	sendCall(ServiceCall call, PeerCard receiver)
String	sendCall(ServiceCall call, String receiver)
String	sendRequest(ServiceRequest request) To be used if the caller would like to handle the reply asynchronously within the method handleResponse(String, ServiceResponse), which will automatically be called in another thread when the response is ready.

Methods inherited from class org.universAAL.middleware.bus.member.BusMember

close, getComment, getLabel, getType, getURI, setComment, setLabel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceCaller

protected ServiceCaller(ModuleContext context)

The default constructor for this class.

Parameters:

context - The module context where the ServiceBus is registered. Note that if no service bus is registered within the passed ModuleContext at the time of creation, this object will not be operational.

Method Detail

busDyingOut

public final void busDyingOut(AbstractBus b)

Description copied from class: BusMember

This method is called when the bus is stopped to announce this to the bus members.

Specified by:

busDyingOut in class BusMember

Parameters:

b - bus on which this member has been registered

See Also:

BusMember.busDyingOut(AbstractBus)

call

public ServiceResponse call(ServiceRequest request)

The "normal" (synchronous) way of calling a service. Use sendRequest(ServiceRequest), if you want to handle the response asynchronously in another thread.

Throws:

NullPointerException - if request is null

inject

public ServiceResponse inject(ServiceCall call,
                              String receiver)

Can be used to inject a ServiceCall to the bus. Compared to the method call(ServiceRequest) there is no matchmaking; the call will be sent directly to a given ServiceCallee. Therefore, this method should NOT be used directly by applications.

Parameters:

call - the ServiceCall .

receiver - the PeerCard of the node that hosts the callee.

inject

public ServiceResponse inject(ServiceCall call,
                              PeerCard receiver)

Can be used to inject a ServiceCall to the bus. Compared to the method call(ServiceRequest) there is no matchmaking; the call will be sent directly to a given ServiceCallee. Therefore, this method should NOT be used directly by applications.

Parameters:

call - the ServiceCall .

receiver - the URI of the bus member that has registered the matching ServiceProfile. Only the identifier of the node that hosts the callee is used from the bus member URI.

call

public final ServiceResponse call(String request)

This method is a way of calling a service using Turtle Strings as input. Turtle Strings are converted to Service Requests.

Parameters:

request - the Turtle String which will be converted into ServiceRequest

Returns:

the expected Service Response

communicationChannelBroken

public abstract void communicationChannelBroken()

This abstract method is called for each member of the bus when the bus is being stopped.

handleReply

public final void handleReply(BusMessage m)

handleResponse

public abstract void handleResponse(String reqID,
                                    ServiceResponse response)

Will be called automatically in a new thread whenever the response corresponding to a previous call to sendRequest(ServiceRequest) is ready.

Parameters:

reqID - the ID returned by the previous call to sendRequest(ServiceRequest).

response - the expected response.

sendRequest

public final String sendRequest(ServiceRequest request)

To be used if the caller would like to handle the reply asynchronously within the method handleResponse(String, ServiceResponse), which will automatically be called in another thread when the response is ready.

Returns:

a unique ID for this request that will be passed to the method handleResponse(String, ServiceResponse) for an unambiguous mapping of responses to requests. Returns null, if this caller does not have the permission for the given request

Throws:

NullPointerException - if the request is null

sendCall

public final String sendCall(ServiceCall call,
                             PeerCard receiver)

sendCall

public final String sendCall(ServiceCall call,
                             String receiver)

getAllServices

public ServiceProfile[] getAllServices()

A method used to instantly retrieve all services available to this caller.

Returns:

all available services.

getMatchingService

public ServiceProfile[] getMatchingService(Service s)

A method used to retrieve a specified service, available to this ServiceCaller.

Parameters:

s - the desired service.

Returns:

the service that is available, or null if no such service is available.

getMatchingService

public ServiceProfile[] getMatchingService(String serviceClassURI)

A method used to retrieve a specified service, available to this ServiceCaller.

Parameters:

serviceClassURI - the class URI of the desired service.

Returns:

the service that is available, or null if no such service is available.

getMatchingService

public ServiceProfile[] getMatchingService(String[] keywords)

A method used to retrieve a service available to this caller, that matches the specified keywords.

Parameters:

keywords - the keywords that should be matched by the service.

Returns:

the service that matches the keywords, or null if no such service is available.

addAvailabilitySubscription

public void addAvailabilitySubscription(AvailabilitySubscriber subscriber,
                                        ServiceRequest request)

Adds an availability subscription, in other words a listener, to receive events about the availability of a specified service.

Parameters:

subscriber - the object which will receive events when the appropriate service registers or unregisters.

request - the request that describes the desired service.

removeAvailabilitySubscription

public void removeAvailabilitySubscription(AvailabilitySubscriber subscriber,
                                           String requestURI)

Removes an availability subscription for this Caller, which was previously added using addAvailabilitySubscription method.

Parameters:

subscriber - the object which used to receive the events.

requestURI - the service that was being monitored.

getMyID

public String getMyID()