Namespace

Namespaces is a concept which allow to tie Services and types to a particular URI^[1]

URI is the Uniform Resource Identifier concept, which allows to define unambiguously a resource

, and avoid name conflicts.

Name conflicts and namespace solution

When you use many modules, you can end having a lot of services, which makes quickly difficult to avoid name conflicts.

The problem

For example, let's looks at this example where there are two services of the same name:

• The AircraftNetwork module publish the aircrafts service, which contain a list of aircrafts from the network. For example, it could be the aircrafts seen by the AWACS
• The Radar module publish another aircrafts service, which contain a list of aircrafts seen by the Radar

We can see that it makes a lot of sense that these two services are both named aircrafts. We could for example consider the following architecture:

However this may not work because even if it is possible to emit the same service by two modules:

• It is not possible by default for publish Services to have more than one provider for the same service^[2]
  However this behavior can be overriden, see Accepting multiple providers
• The two aircrafts service represent different data, and may even not contain the same data content

The solution

To fix this problem, the solution is to add a namespace URI to the two aircrafts services, so they will still keep their name, but they will live in two different namespaces:

Namespaces can be defined for services declarations and types declarations, and referenced in the modules services interface.

Note that services of a specified namespace can access types of the same namespace, or types with no namespace declaration.

Usage in Java modules

The elements which have a namespace and which are used in Java modules are:

• The services through the ServiceInstance class
• The types through the Type class

These elements implement the NamespaceElement interface which provide the following methods:

• The NamespaceElement.getKey() method return the NamespaceKey of the element

For example, suppose the following service declaration:

      <services>
        <namespace uri="http://aircrafts.com" >
           <subscribe name="aircrafts" >
              <data name="aircrafts" type="aircraftsArray" />
           </subscribe>
        </namespace>
      </services>

The http://aircrafts.com:aircrafts service key can be checked with:

      public class myModule {
         private NamespaceKey AIRCRAFTS = NamespaceKey.createKey("http://aircrafts.com", "aircrafts");  
         public void subscribe(ServiceInstance service) {
            NamespaceKey key = service.getKey();
            if (key.equals(AIRCRAFTS)) {
              .. do something with the aircrafts
            }
         }
      }

Etting a service instance in a module

The Module.getService(String, String) and Module.getService(NamespaceKey) methods allow to get the service instance with a specified name and URI.

For example:

      public class myModule {
         private ServiceInstance acService = null;
         public void init(Module module) {
            NamespaceKey aircraftsKey = NamespaceKey.createKey("http://aircrafts.com", "aircrafts");  
            acService = module.getService(aircraftsKey); // could also be module.getService(http://aircrafts.com", "aircrafts")
         }
      
         public void start() {
           ... // populate the aircrafts service
           acService.invoke();
         }
      }

Example

In our example, we have two aircrafts service:

• The first one contain a list of aircrafts from the network. We will use the "http://aircrafts.com" URI to specify its namepace
• The second one contain a list of aircrafts seen by the Radar. We will use the "http://radar.com" URI to specify its namepace

Services declaration

We will have the following services declaration:

      <services>
        <namespace uri="http://aircrafts.com" >
           <publish name="aircrafts" >
              <data name="aircrafts" type="aircraftsArray" />
           </publish>
        </namespace>
        <namespace uri="http://radar.com" >
           <publish name="aircrafts" >
              <data name="aircrafts" type="aircraftsArray" />
           </publish>
        </namespace>
      </services>

Types declaration

In our case, we have also the same aircraftsArray type names, so we should also declare our two types in separate namespaces:

      <services>
        <namespace uri="http://aircrafts.com" >
           <structType name="aircraft" >
      ...
           </structType>
           <arrayType name="aircraftsArray" type="aircraft" />
        </namespace>
        <namespace uri="http://radar.com" >
           <structType name="aircraft" >
      ...
           </structType>
           <arrayType name="aircraftsArray" type="aircraft" />
        </namespace>
      </services>

Interfaces declaration

We should refer to the proper services using their associated namespaces:

      <module name="AircraftSystem" >
         <interfaces>
            <subscribe service="aircrafts" uri="http://aircrafts.com" />
            <subscribe service="aircrafts" uri="http://radar.com" />
         </interfaces>
      </module>