What is an oplet?

An oplet is the unit of deployment of code on the Oplet Runtime Environment (ORE). It is implemented as a Java JAR file that is downloaded across the network from a server to the network element (NE) hosting the ORE. Each oplet can provide zero or more services that add new functionality to the NE. Some possible services might be:

• traffic monitoring;
• intrusion detection;
• active networking;
• accounting and billing;
• closed-loop feedback;
• error detection, diagnosis, and remediation.

The oplet JAR file contains the class files that implement the services and any auxiliary resources that they require, such as data files and images. The oplet can also contain subsidiary JAR files to help organize these resources. The JAR file also contains a manifest that contains meta-data for the oplet, including:

• signatures for the contents of the JAR file;
• declarations for the entities provided by the oplet;
• dependencies on other ORE services;
• version and control information.

Declaring an oplet

An oplet is declared by providing an Oplet header in the manifest. This header gives the fully qualified name of a class in the oplet JAR file that implements the com.nortelnetworks.ore.Oplet interface. The ORE uses this class to:

• discover dependencies the oplet has on other services;
• manage the lifecycle of the oplet;
• discover any auxiliary resources;
• check version information.

Although it is not difficult to implement this interface yourself, unless you need to have special control over the oplet you will typically not directly implement Oplet yourself. In this case the ORE itself will create a generic oplet that uses the com.nortelnetworks.ore.ManifestOplet interface to start and stop services. You must provide an implementation of this interface and specify its fully qualified name in the Oplet header in the manifest. This generic oplet uses extra headers in the oplet manifest to provide information about your oplet to the ORE.

Here is an example of the manifest headers for a simple oplet based on ManifestOplet:

Oplet: mypackage.MyOplet
Oplet-Services: mypackage.MyService
Oplet-Dependencies: otherpackage.OtherService

This declares that the oplet JAR file contains an oplet implemented by a class with the fully qualified name mypackage.MyOplet which provides a service with the fully qualified name mypackage.MyService. In addition, this oplet uses facilities from the otherpackage.OtherService service provided by another oplet. This means that this oplet has a dependency on otherpackage.OtherService.

Oplet dependencies

When an oplet uses a service provided by a different oplet it creates a dependency on that service. This means that some oplet providing that service must be installed and started before this oplet can be started. The ORE tracks which services are currently running, and checks that the dependencies declared by the oplet are satisfied when it is started. If they are not satisfied, a runtime error will be given and the oplet will not be started. An oplet should not declare a dependency on any services that it provides itself: it should only declare them for services provided by other oplets.

The ORE gives each oplet its own name space to protect it from inadvertent name clashes. When a dependency is created, the ORE connects the name space of the oplet providing the service to the dependent oplet. This breaks down the insulation between the two oplets and enables the dependent oplet to use classes and methods in the service. When the dependency is removed, the access to the names provided in the other oplet is also removed. You must not retain any references to objects acquired via a service (including the service implementation object itself) after you release the service. Doing so will prevent the JVM from unloading the code for the oplet that provided the service, and attempting to use these stale objects will have unexpected and probably bad consequences.

If you attempt to acquire a service that has not been started, the ORE will generate a runtime error. This typically is an indication that the Oplet-Dependencies header does not have correct or complete declarations. Check that the service you are trying to acquire is listed in the header, and that it is spelled correctly.

The oplet lifecycle

There are four distinct phases in an oplet lifecycle:

1. install
2. start
3. stop
4. uninstall

Installing an oplet

An oplet is installed by calling OpletRuntimeEnvironment.install. The oplet JAR file is loaded from the location specified, and checked to ensure that it has a valid manifest and that it does contain an oplet implementation. The ORE calls the oplet's install method to give it an opportunity to perform any special processing. If you are using ManifestOplet you no longer have any control over this phase of the lifecycle.

The oplet's dependencies are not resolved at this time. Specifically, this means that the oplet cannot use any services provided by another oplet. Any attempt to do so will result in a java.lang.NoClassDefFoundError exception.

Services provided by the oplet are not started yet.

The result of installing an oplet is an oplet context. An OpletContext is an object that encapsulates the runtime representation of an oplet. Most ORE methods require an OpletContext as one of their arguments.

Starting an oplet

Once an oplet has been installed it can be started by calling OpletRuntimeEnvironment.start. The ORE calls the oplet's start method to allow the oplet to start the services that it provides. Before making this call, the ORE resolves the oplet's dependencies. To do this the ORE checks that all of the services that the oplet depends on are available. If any of these services is not available, the ORE generates a runtime error.

An oplet can also declare a dependency on JAR files that it provides. When the ORE resolves the oplet's dependencies the contents of these JAR files are also available for use by the oplet.

An oplet's main task when it is started is to create, start, and register its services. The ORE places no constraints on the interface between the oplet and its services. To ensure that only the oplet can create and start and stop the services it is recommended that the service's constructors and the other administration methods have package access, not public access. An oplet that is based on ManifestOplet does, however, have some extra constraints.

Once a service has been created and started it can be registered with the ORE. This makes it available for use by other oplets. The oplet start method should call OpletRuntimeEnvironment.register to perform the registration. The ORE automatically registers the services of a ManifestOplet after it is started.

Stopping an oplet

An oplet is stopped by calling OpletRuntimeEnvironment.stop. If one of the oplet's services has been acquired by another oplet, and has not been released yet, the ORE generates a runtime exception, and the oplet is not stopped. To force an oplet to be stopped even if it is still in use, you can call OpletRuntimeEnvironment.kill. This method effectively kills any dependent oplets, then stops this oplet.

The oplet's main tasks when it is stopped are to discard any references to objects from other oplets, release any services that is has acquired, and to unregister any services that it has provided. The ORE automatically unregisters the services of a ManifestOplet after it is stopped.

Uninstalling an oplet

An oplet is uninstalled by calling OpletRuntimeEnvironment.uninstall. When it is installed, the ORE relinquished any references it has to the oplet's objects. This enables the JVM to garbage collect the oplet.