de.tum.in.DWARF
Class TemplateService

java.lang.Object
  BasicServicePOA
      de.tum.in.DWARF.TemplateService

All Implemented Interfaces:

java.lang.Runnable

public abstract class TemplateService
extends BasicServicePOA
implements java.lang.Runnable

Base class for DWARF services. When setting up a new Service, extend this class and override the abstract methods:

• createAbilityObject - This method must return a valid CORBA object that implements the interfaces specified in the corresponding ServiceDescription (connector protocol and type)
• createNeedObject - This method must return a valid CORBA object that implements the interfaces specified in the corresponding ServiceDescription (connector protocol and type)
• runThread - This method can be used to manage additional tasks (e.g. read/write a TCP-socket, ...). In general you implement a

  while(shouldRun()) {...}

  , but be careful, not to consume 100% of (niced) CPU time, this would queue your CORBA events. If you do not require this method, let the thread die by implementing an empty runThread method.

To ease implementation, there is a defaultMainMethod whose use also allows calls to the getORB method.

In addition there are some methods which have empty implementations. Override them if you require extra behaviour at certain points during startup:

• onCorbaInit - This method is called directly after CORBA is initialized and before the Service is registered at the ServiceManager. Note: You have to call the defaultMainMethod method to get access to this method.
• onRegister - This method is called directly after the Service object is registered at the ServiceManager and directly before the main thread is blocked in the ORB. Note: You have to call the defaultMainMethod method to get access to this method.
• onStartService - This method is called directly after the Service is started, which means that all need and ability objects are created and the control thread is started (see runThread method)

Distributed Wearable Augmented Reality Framework - http://wwwbruegge.in.tum.de/projects/dwarf/doc/

For further questions about DWARF, please contact us at dwarf@augmentedreality.de For questions about this particular service, contact

Constructor Summary

TemplateService()
Builds up a new instance of the TemplateService and sets the running flag to false, because startService will set the run flag to true.

Method Summary

void	addAbility(java.lang.String name, java.lang.Object obj) Adds an ability to the map storing all abilities.
void	addNeed(java.lang.String name, org.omg.CORBA.Object obj) Adds a need to the map storing all needs.
void	blockUntilRunning() Call this method from your main loop (out of the runThread method) if you want to wait until the whole service has been started.
void	blockUntilStopped() Call this method from your main loop (out of the runThread method) if you want to wait until the whole service has been stopped.
protected boolean	checkAbilityObject(org.omg.CORBA.Object ability, AbilityDescription abilityDescription) Parse all connectors of the given ability description.
protected boolean	checkNeedObject(org.omg.CORBA.Object need, NeedDescription needDescription)
protected abstract org.omg.CORBA.Object	createAbilityObject(AbilityDescription abilityDescription) Implement this method to create CORBA objects that manage specified AbilityDescriptions.
protected abstract org.omg.CORBA.Object	createNeedObject(NeedDescription needDescription) Implement this method to create CORBA objects that manage specified NeedDescriptions.
protected static void	defaultMainMethod(java.lang.String[] argv, org.omg.PortableServer.Servant service, java.lang.String serviceName) This method Gets the ORB and the ServiceManager, registers the Service with its name and blocks the main thread until all other threads died.
java.util.Set	getAbilities()
org.omg.CORBA.Object	getAbility(java.lang.String name)
protected java.util.Map	getAbilityMap()
org.omg.CORBA.Object	getNeed(java.lang.String name)
protected java.util.Map	getNeedMap()
java.util.Set	getNeeds()
protected org.omg.CORBA.ORB	getOrb() Returns the ORB, but this method is only supported, when the defaultMainMethod was called.
protected org.omg.PortableServer.POA	getPOA() Returns the POA, but this method is only supported, when the defaultMainMethod was called.
protected java.lang.String	getServiceAttribute(java.lang.String name)
ActiveServiceDescription	getServiceDesc()
protected ServiceManager	getServiceManager() Returns a reference to the ServiceManager.
java.lang.String	getStatus() This method is from the DWARF Service interface.
protected void	onCorbaInit() This method is executed direct after the CORBA is initialized and before the Service is registered at the ServiceManager.
protected void	onRegister() This method is executed direct after the registration of the Service at the ServiceManager.
protected void	onStartService() This method is executecuted direct after the start of the Service at the ServiceManager.
protected void	parseAbilities() Parse all Abilities, for each found do: -# Check for its type and connector protocol.
protected void	parseNeeds()
void	run() A new Thread is started and runThread method is called
abstract void	runThread() Implement this method to set up some kind of main loop, ...
protected boolean	shouldRun() Indicates whether the service should run or not.
void	startService(ActiveServiceDescription serviceDescription) This method is called by the service manager on startup.
void	stopService(ActiveServiceDescription arg0) This method is called by the service manager on shutdown of the service.

Methods inherited from class java.lang.Object

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

Constructor Detail

TemplateService

public TemplateService()

Builds up a new instance of the TemplateService and sets the running flag to false, because startService will set the run flag to true.

Method Detail

getOrb

protected org.omg.CORBA.ORB getOrb()

Returns the ORB, but this method is only supported, when the defaultMainMethod was called.

Returns:

the ORB

getPOA

protected org.omg.PortableServer.POA getPOA()

Returns the POA, but this method is only supported, when the defaultMainMethod was called.

Returns:

the POA

getServiceManager

protected ServiceManager getServiceManager()

Returns a reference to the ServiceManager.

Returns:

The ServiceManager

getStatus

public java.lang.String getStatus()

This method is from the DWARF Service interface. It is not necessary to implement it, however, you can provide more or less useful status information to the service manager and other services interested in (e.g. DIVE)

startService

public void startService(ActiveServiceDescription serviceDescription)

This method is called by the service manager on startup. Use this method as the core initialization routine, parsing the service's description for needs and abilities and instantiating corresponding objects. The sequence of action is as follows:
-# Back up the service description to a private variable.
-# Parse all Needs and Abilities
-# Instantiate the ServiceControl object and start it in a new thread.
Warning: This method should only be called by the service manager.

Parameters:

serviceDesc - The description of this service. This is a service's only opportunity to get hold of its own service description. If it is needed later on, store a copy of it in a member variable

stopService

public void stopService(ActiveServiceDescription arg0)

This method is called by the service manager on shutdown of the service. We use this method to delete the Service Control object, assuming that it takes all necessary means in its destructor to stop the controller thread(s). In addition, we delete all objects handling the service's needs and abilities. Warning: This method should only be called by the service manager.

Parameters:

serviceDesc - The service's description given by the service manager

getAbilities

public java.util.Set getAbilities()

Returns:

Set of String s that are the abilitie's names.

getNeeds

public java.util.Set getNeeds()

Returns:

Set of String s that are the need's names.

addAbility

public void addAbility(java.lang.String name,
                       java.lang.Object obj)

Adds an ability to the map storing all abilities.

Parameters:

name - the ability's name

obj - the object representing the ability

getAbility

public org.omg.CORBA.Object getAbility(java.lang.String name)

Parameters:

name - the ability's name

Returns:

the object representing the ability or null if no ability with this name exists

addNeed

public void addNeed(java.lang.String name,
                    org.omg.CORBA.Object obj)

Adds a need to the map storing all needs.

Parameters:

name - the need's name

obj - the object representing the ability

getNeed

public org.omg.CORBA.Object getNeed(java.lang.String name)

Parameters:

name - the need's name

Returns:

the object representing the need or null if no need with this name exists

getServiceDesc

public ActiveServiceDescription getServiceDesc()

Returns:

a new instance (copy) of the service's service description

parseAbilities

protected void parseAbilities()

Parse all Abilities, for each found do:
-# Check for its type and connector protocol.
-# Based on type, instantiate an object from a specific class (this is dependent on the actual service).
-# Check whether this object can handle the specified protocol.
-# Store the Ability description in a private hashmap. .

Parameters:

serviceDesc - The description of this service.

createAbilityObject

protected abstract org.omg.CORBA.Object createAbilityObject(AbilityDescription abilityDescription)

Implement this method to create CORBA objects that manage specified AbilityDescriptions. The created object has to implement the correct protocol(s) of the connectors specified in the AbilityDescription.

Parameters:

abilityDescription - The AbilityDescription for which an object is to be created.

Returns:

The Object managing the AbilityDescription.

checkAbilityObject

protected boolean checkAbilityObject(org.omg.CORBA.Object ability,
                                     AbilityDescription abilityDescription)

Parse all connectors of the given ability description. Test if the given object implements the necessary interface using _is_a().

Returns:

true if the object matches all connectors, false otherwise

parseNeeds

protected void parseNeeds()

createNeedObject

protected abstract org.omg.CORBA.Object createNeedObject(NeedDescription needDescription)

Implement this method to create CORBA objects that manage specified NeedDescriptions. The created object has to implement the correct protocol(s) of the connectors specified in the NeedDescription.

Parameters:

needDescription - The NeedDescription for which an object is to be created.

Returns:

The Object managing the NeedDescription.

checkNeedObject

protected boolean checkNeedObject(org.omg.CORBA.Object need,
                                  NeedDescription needDescription)

run

public final void run()

A new Thread is started and runThread method is called

Specified by:

run in interface java.lang.Runnable

runThread

public abstract void runThread()

Implement this method to set up some kind of main loop, ...

shouldRun

protected boolean shouldRun()

Indicates whether the service should run or not.

Returns:

if the service should run or not

getAbilityMap

protected java.util.Map getAbilityMap()

getNeedMap

protected java.util.Map getNeedMap()

blockUntilRunning

public void blockUntilRunning()

Call this method from your main loop (out of the runThread method) if you want to wait until the whole service has been started.

blockUntilStopped

public void blockUntilStopped()

Call this method from your main loop (out of the runThread method) if you want to wait until the whole service has been stopped.

defaultMainMethod

protected static final void defaultMainMethod(java.lang.String[] argv,
                                              org.omg.PortableServer.Servant service,
                                              java.lang.String serviceName)

This method Gets the ORB and the ServiceManager, registers the Service with its name and blocks the main thread until all other threads died. You just have to Create the Service object.

Parameters:

argv - The real main methods command lines arguments

service - The Service object

serviceName - The Service's name

getServiceAttribute

protected java.lang.String getServiceAttribute(java.lang.String name)

onCorbaInit

protected void onCorbaInit()

This method is executed direct after the CORBA is initialized and before the Service is registered at the ServiceManager. Does nothing. Override it if you need specialized behaviour.

onRegister

protected void onRegister()

This method is executed direct after the registration of the Service at the ServiceManager. Does nothing. Override it if you need specialized behaviour.

onStartService

protected void onStartService()

This method is executecuted direct after the start of the Service at the ServiceManager. Does nothing. Override it if you need specialized behaviour.