net.larsan.norna
Interface ServiceRegistry


public interface ServiceRegistry

The service registry can be used by services to search for other services and in also to start or stop them. All services can be fetched from the the Norna Namespace, as well as from this class but all action requiring a unique identifier for the service such as start or stop must use the service Namespace ID.

The registry is available on all implementations on the fixed namespace ID: "/norna/registry". This if is guarantied never to return null by the framework and the path "/nonra" is reserved. The registry namespace ID is also a static identifier on this interface.

The relationship between service context URLs and services IDs is not necessarry one to one since the framework cannot guarrantee that no two services does not specify the same public ID. So the getByPublicID method return an iteration if service Namepsace IDs but getByURL return the service handle of a unique service.

URLs passed to methods of the registry behaves as if the registry is a Context located at the root of the Norna Namespace. so that a call to getByURL with the following values are all guarranteed to return the same service given that the framework is rooted at 'localhost':

       services/calculator/
       /services/calculator/
       norna://localhost/services/calculator/
 

The registry is also responsible for notifying any listeners of additions and changes to the Norna context in regards to the services themselves. A registry is allowed to transmit any changes made to the Norna namespace but is not required to do so.

Searches on the registry uses regular expression matching on the following service properties:

The registry uses the ServicePermission to guard access to the services and the controller methods within the registry.

Methods returning iterators of services will not return services the caller do not have access to. This means that the registry must check access permission before returning any values from such methods.

All methods on the service registry is guarrantied to be thread safe.

Version:
Alpha-0.2 / 2002-10-06 21:37
Author:
Lars J. Nilsson
See Also:
Context Namespace

Field Summary
static java.lang.String NAMESPACE_ID
          The fixed registry namespace ID, "/norna/registry"
 
Method Summary
 void addRegistryListener(java.util.Properties filter, RegistryListener listener)
          Add a service listener to the registry.
 void addRegistryListener(RegistryListener listener)
          Add a service listener to the registry.
 java.util.Iterator getByPublicID(java.lang.String publicID)
          Get an iterator of service context URLs by an public ID.
 ServiceHandle getByURL(java.lang.String url)
          Get a service handle by context URL.
 Environment getEnvironment()
          Get the envoronment of the service.
 SoftwareInfo getSoftwareInfo(java.lang.String url)
          Get service software info.
 java.util.Iterator list()
          List all available services.
 void removeRegistryListener(RegistryListener listener)
          Remove a registry listener.
 java.util.Iterator search(java.util.Properties attributes)
          Seach for a service.
 void start(java.lang.String url)
          Start a service.
 void stop(java.lang.String url)
          Stop a service.
 

Field Detail

NAMESPACE_ID

public static final java.lang.String NAMESPACE_ID
The fixed registry namespace ID, "/norna/registry"

See Also:
Constant Field Values
Method Detail

getEnvironment

public Environment getEnvironment()
Get the envoronment of the service. This runtime environment object is guarrantied by the framework and contains the root address of the installation.

Returns:
The framework environment

getByPublicID

public java.util.Iterator getByPublicID(java.lang.String publicID)
Get an iterator of service context URLs by an public ID. Normally this will return a trivial iterator since services should strive to avoid ID clashes as far as possible.

Parameters:
publicID - Service id as returned by getPublicID
Returns:
An iterator of the service context URLs as strings

getByURL

public ServiceHandle getByURL(java.lang.String url)
Get a service handle by context URL. The registry will resolve the URL relative to the current namespace root. This method might throw a security exception if the caller is ot allowed to access the service.

This method return null if the service is not found or the service is not ready.

Parameters:
url - Service context URL
Returns:
A ServiceHandle to the a service, or null if not found or not ready

search

public java.util.Iterator search(java.util.Properties attributes)
                          throws java.util.regex.PatternSyntaxException
Seach for a service. The search is performed on the service SoftwareInfo and it's URL using properties mapping an attrinute to a regular expression. The searchable property and their corresponding values are:

   "url" - Service context URL
   "puid" - Service public ID
   "name" - Service name
   "originator" - Service vendor
   "release" - Service release tag
   "version" - Service software version

The search returns an iterator over service URLs as strings.

Parameters:
attributes - Search attributes matching property names to regular expressions
Returns:
An iterator of the service context URLs matching the search criteria as strings
Throws:
java.util.regex.PatternSyntaxException - If any regexp patter is invalid

list

public java.util.Iterator list()
List all available services. This returns an iterator over service context URLs as strings. Should the caller not be permitted to access any of the existing services they should not be included in the iterator.

Returns:
An iterator over service context URLs the caller has access to

getSoftwareInfo

public SoftwareInfo getSoftwareInfo(java.lang.String url)
Get service software info. This returns a software info object for the service if it can be found. Should the caller not have permission to access the service this method will silently fail.

Parameters:
url - Service context URL as a string
Returns:
A SoftwareInfo object for the service, or null if not found

start

public void start(java.lang.String url)
           throws NoSuchServiceException
Start a service. This method is subject to permission checks aganst a ServicePermission object with a "start" action.

Parameters:
url - Service context URL as a string
Throws:
NoSuchServiceException - If no service with the nuid is found

stop

public void stop(java.lang.String url)
          throws NoSuchServiceException
Stop a service. This method is subject to permission checks aganst a ServicePermission object with a "stop" action.

Parameters:
url - Service context URL as a string
Throws:
NoSuchServiceException - If no service with the nuid is found

addRegistryListener

public void addRegistryListener(RegistryListener listener)
Add a service listener to the registry. The service events are subject to security checks and the registry must not deliver events to listeners that does not have a "get" service permission on the target url.

Parameters:
listener - Register listener

addRegistryListener

public void addRegistryListener(java.util.Properties filter,
                                RegistryListener listener)
Add a service listener to the registry. The service events are subject to security checks and the registry must not deliver events to listeners that does not have a "get" service permission on the target url.

The property object maps properties to reguslar expressions that are used to filter events. Only if all properties and their regular expression match a service will the event go through. The filter properties are the same as those in search.

Parameters:
filter - Event filter properties
listener - Register listener

removeRegistryListener

public void removeRegistryListener(RegistryListener listener)
Remove a registry listener.

Parameters:
listener - Listener to remove