Using the API

In more complex cases—if you need to add your own properties or services to the context—you will have to use the context API. For details, see Creating a new context and Modifying a context.

Note

You can use the context API in conjunction with a deployment descriptor. In other words, you can extend the syntax of the deployment descriptor and process added XML elements with a dedicated handler. For more information, see Extending the deployment descriptor.

You can initialize the default context through the API IltDefaultContext, that is, the default implementation of the interface IlpContext.

When you initialize the JViews TGO library (by calling IltSystem.Init ), an instance of the default context is created. You can retrieve it by using the method GetDefaultContext. This method is invoked by the default constructor of classes using contextual information and services ( IltDefaultDataSource, for example).

How to retrieve the default context through the API

IlpContext context = IltSystem.GetDefaultContext();

Creating a new context

Generally, you are led to create new contexts when your application is to run in a multiuser environment and you want each user to have his/her own context.

To create an instance of IltDefaultContext, simply call:

IltDefaultContext context = new IltDefaultContext();

To use this new context, you must pass the context parameter to the constructor of each class making use of it in order to bypass the default context returned by GetDefaultContext. For example, to create a data source, you should not use the default constructor new IltDefaultDataSource() , because using it would initialize the default context, but use instead the constructor that takes a context as its parameter, that is, new IltDefaultDataSource(context) .

How to create and initialize a context through the API

IlpContext context = new IltDefaultContext();
context.addService (IlpTypeConverter.class, new 
IlpDefaultTypeConverter(context));

Modifying a context

You may want to modify an existing context to add your own services or properties.

How to change a service in a context

You can add a service to a context or replace an existing service with a new one using the addService method.

If you want to change the synchronization strategy to use regular Java™ synchronization and not the default strategy that uses the event thread, write the following line:

context.addService(IlSynchronizationStrategy.class,
                   new IlSynchronizeOnLockStrategy());

The first parameter of the addService method is a class that defines the service to be changed (usually this parameter is an interface because a service is generally defined by an interface). The second parameter is an implementation of this service. In other words, the second parameter is supposed to implement the class specified by the first parameter.

How to remove a service from a context

To remove a service from the context, you use the method removeService with a single parameter to indicate the service to be removed:

context.removeService(IlSynchronizationStrategy.class)

The default context implementation allows you to store properties. The following methods are available to help you handle the context properties:

public void setProperty(String name, Object property) Sets the value of a property in the context.
public Object getProperty(String name) Returns the value of a property in the context or null if the property is not defined.
public Map getProperties() Returns the collection of all properties defined in the context.

You can directly modify this Map by adding or removing your own context properties.

Creating a context in background

It is possible to initialize TGO in a background thread, which automatically invokes the IltSystem method along with the creation of a new context. It also initializes the TGO static resources that are usually only required at rendering time. This improves the graphic component initialization time (usually done at the Event Dispatch thread) and also provides some control over the initialized TGO static resources.

How to initialize TGO in background

When the JViews TGO application context is created (using the method IltSystem), many predefined resources are initialized, such as alarm states and default values for severities. Other resources such as the different predefined object types are initialized on an as needed basis, when they are first referenced by the application. This process takes time and can slow down your application display time, for example, when you try to display a large number of different predefined nodes for the first time.

You can prevent such slowdowns by warming up TGO with an extended context initialization that is carried out on a background thread by the IltSystemInitializer utility class. This is useful for applications that perform time consuming tasks during startup and/or initialization (such as establishing remote connections, waiting for user authentication, and so on).

The IltSystemInitializer class creates the TGO application context (by internally invoking the IltSystem.Init method) extending the initialization to some resources usually lazily initialized by the rendering of predefined objects. This is done on a separate thread, concurrently with the time consuming part of your application initialization.

The following example illustrates the process:

Before starting a routine that is time consuming, start the TGO initialization:

  // Start initialization on a worker thread
  IltSystemInitializer.Init("my/deployment/file.xml");

When you are ready to start your UI, check for correct TGO initialization and continue:

  // Wait for TGO initialization
  // This is a blocking method!
  IltSystemInitializer.WaitInitialization();

  // You can check for initialization errors
  Throwable error = IlpSystemInitializer.GetError());

  // The context is already initialized
  // There is no need to invoke IltSystem.Init()
  _context = IltSystem.GetDefaultContext();
  _tree = new IlpTree(_context);

Note that this technique is useful when the IltSystemInitializer method executes in parallel with a time consuming task.

Current section

Initializing a context