Skip Headers
Oracle® Communications Network Integrity Developer's Guide
Release 7.1

E23701-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Working with Processors

In Oracle Communications Network Integrity, processor entities are the building-blocks for actions, as they implement atomic sub-functions for actions.

For example, an SNMP processor is included in an action to poll network devices; a modeler processor is included in an action to model raw SNMP data from a network device and add it to a database. Combined, these two processors comprise a discovery action that polls SNMP-enabled network devices and persists the modeled SNMP data.

By adding multiple processors to an action, the action performs several complex function by executing the processors according to the sequence in which they were added to the action.

Processors are of different types:

Unlike actions, processors are not visible in Network Integrity.

To create a processor, see the following:

To configure a processor, see the following:

To configure the input and output parameters for the processor, see the following:

To configure property groups and properties for a processor, see the following:

To view an outline of code generation for processors, see the following:

To view an outline of processor implementation, see the following:

Creating Processors

You can create a processor independently or create a processor in the process of adding it to an action. The latter method is recommended because it automatically adds the processor to the list of processors that the action uses. And it also ensures that you can create only the supported types of processors for the current action.

To create a processor, see the Design Studio Help.

Configuring Processors

The main steps in configuring a processor using the processor editor in Design Studio include:

  • Using the Properties tab to define properties that are passed to the processor.

  • Using the Context Parameters tab to define the processor's inputs and outputs.

  • Using the Details tab to specify the implementation class.

After you configure an action and its processors, complete the action by coding the implementations for the processors.

About Context Parameters

The processor editor has a Context Parameters tab that you can use to configure the input and output parameters for the processor. Both input and output parameters are optional for a processor.

For extensibility, configure the processor to produce an output parameter that is available to other processors to continue data processing. Typically, the output parameter should be the Oracle Communications Information Model entity that the processor models: for example, LogicalDevice or PhysicalDevice.

See Oracle Communications Information Model Reference and Network Integrity Information Model Reference for further information about the Information Model.

After adding input and output parameters for the processor using Oracle Communications Design Studio, these parameters appear in tabular format in the Context Parameters area of the processor editor. Design Studio generates the request and response Java classes based on the input and output parameters.

About Properties and Property Groups

A property group is a logical container configured on a processor. A property group can be added to multiple processors. Property group names must be unique within a processor.

Properties are added to property groups and are assigned property values to pass to the processor, either hard-coded or at run time.

Property groups do not inherently pass any values to the processor other than the values belonging to its properties.

Property groups and properties are configured on processors on the Properties tab of the processor editor.

Property groups can be configured as Managed groups, where the values for the properties it contains can be set at run time using the MBean interface. See Network Integrity System Administrator's Guide for more information.

Property groups can be configured as Map groups, where the property group produces a simplified API for properties that are used as maps.

A Java class is generated for the property group so that you can extend a cartridge to access the property values it contains using a generated interface.

A property consists of a name-value pair that is passed to the processor through the property group. Depending on how the property group is configured, the property value is either hard-coded, or provided at run time through the MBean interface. Property names must be unique within the property group.

Properties can be configured with the following options:

  • Property values can be set using a cartridge model variable, where you can specify the value of the variable at deployment time. To set a property value with a cartridge model variable, the value string must begin and end with a percentage (%) symbol, as in the following example:

    %Property_Value%
    
  • Properties can be configured as Secret values, to pass encrypted values at deployment time using the MBean interface. The property value must be encrypted before it can be entered in the MBean interface. See Network Integrity System Administrator's Guide for more information.

For more information on adding property groups to a processor, adding properties to a property group, and setting cartridge model variables, see the Design Studio Help.

About Generated Code

This section describes code generation for processors in Network Integrity:

About the Location for Generated Code

Design Studio code-generates the relevant Java classes for the processor. The generated code is located at:

Studio_Workspace\NI_Project_Root\generated\src\Project_Default_Package\Processor_Type\Processor_Implementation_Prefix

where:

  • Studio_Workspace is the Eclipse Workspace root

  • NI_Project_Root is the Network Integrity project root

  • Project_Default_Package is the default package configured at the cartridge editor

  • Processor_Type is run time following action types:

    • discoveryprocessors

    • importprocessors

    • assimilationprocessors

    • detectionprocessors

    • resolutionprocessors

  • Processor_Implementation_Prefix is the action implementation prefix in lowercase.

About the Processor Interface

Every processor has a generated interface. The generated processor interface class is named Processor_NameProcessorInterface.java.

In general, the generated processor interface has the invoke method defined. The interface has two forms of invoke methods, depending on whether there is an output parameter defined for the processor.

// Signature for processor which does not have output parameters
public void invoke(<Processor_Specific_Context> context,
               ExampleProcessorRequest request) throws ProcessorException {
       // TODO Auto-generated method stub
 
// Signature for processor which has output parameters
public ExampleProcessorResponse invoke(<Processor_Specific_Context> context,
               ExampleProcessorRequest request) throws ProcessorException {
       // TODO Auto-generated method stub
       return null;
}
 

The generated processor interface has a slightly different signature, depending on the type of processor: for example, Processor_Specific_Context differs between processor types. See individual chapters on specific processors for more information.

About the PropertyGroup and Properties Classes

A properties class is always code-generated for the processor, whether the processor has property groups and properties configured or not. The properties class is used as an input parameter for the constructor of the generated request class.

The generated properties class is named Processor_NameProcessorProperties.java.

The generated properties class has a public method, String[] getValidProperties(). This method returns a string array that contains a list of valid property group names configured for this processor. If the processor has no property groups configured, this method returns an empty array.

If the processor has property groups and properties configured, for each property group a PropertyGroup class is code-generated.

The generated PropertyGroup class is named PropertyGroup_NamePropertyGroup.java.

The generated PropertyGroup represents the configured property group and all of its properties. The generated properties class has the getter methods to get each PropertyGroup directly, and has all the setter methods to modify the property values.

The generated PropertyGroup class has a public method, String[] getValidProperties(). This method returns a string array that contains a list of valid properties names configured for this property group. If the property group has no property configured, this method returns an empty array.

If the property group is not configured as a Map group, the generated PropertyGroup class provides getter methods for all the properties configured in this property group.

If the property group is configured as a Map group, the generated PropertyGroup class does not provide getter methods for all the properties configured in this property group. Instead, the API for the property group resembles a Java Map, where the property values are retrieved and set using the property name passed as a value.

About Processor Implementation

Implementation of the processor is done in the processor editor using the Details tab. See the Design Studio Help for specific configuration details.

You can click the Implementation Class link to open the Java editor for this implementation Java class. Design Studio auto-generates the skeleton Java implementation class, which implements the processor interface with an empty implementation method.

You must decide whether to complete implementing the method. Sometimes, if the processor was changed later (for example, by adding output parameters or removing parameters) the implementation class displays a compiling error. This is expected because the skeleton implementation class is regenerated. You must modify the implementation class to match the changed processor interface.

For information about how to implement a processor, see the individual processor section.

About the Processor Finalizer

When a processor deals with resources (for example, sockets and files), it is necessary to clean up the resources used or created while the processor executes. Using a finalizer on the processor ensures that the used or created resources get cleaned up, whether the action fails or is successful. When implemented, the finalizer cleans up the resources used or created by the processor. It is not mandatory to implement the finalizer if the processor does not deal with a resource, or if the resource is used only within the processor (in which case the processor implementation should make sure the local resource is closed properly). The processor must implement the finalizer if the processor allocates a resource that is to be output for use by other processors.

Finalizers that are not inside a For Each loop are called by the action controller class (code-generated) before it completes. Finalizers that are inside a For Each loop are called by the action controller class at the end of the For Each loop. In all cases, finalizers are called in the reverse order to which they are registered (finalizers registered first are called last; finalizers registered last are called first).

ProcessorFinalizer

The processor implementation class must implement the interface oracle.communications.sce.integrity.sdk.processor.ProcessorFinalizer to have the action controller clean up the resources that are used or created by the processor. If a processor does not use or create a resource, it does not implement the ProcessorFinalizer interface.

The processor defines only one method:

public void close(boolean failed);

The processor that implements the ProcessorFinalizer interface must implement this method to close all the resources used or created during the execution of this processor. This method takes an input parameter as Boolean. If there is an exception during the execution of the processors, the action controller calls the finalizer by passing True to this method; otherwise the action controller calls the finalizer by passing False to the method, in the successful case. The processor might implement the close logic differently for both successful and failed scenarios: for example, if it is a failed scenario, the close method might log an error message before closing the resources.

The following code shows how to implement the ProcessorFinalizer for a sample processor:

public class SampleProcessorImpl implements SampleProcessorInterface, ProcessorFinalizer {
         public SampleProcessorResponse invoke(SampleProcessorRequest request) 
                 throws ProcessorException {
                 // Implement the Processor here…
         }
 
         public void close(boolean failed) {
                 if(failed) {
                           // something is failed, log extra error message here.
                 }
                 // close the InputStream here.
                 try {
                          myInputStream.close()
                 } catch(IOException ioe) {
                          // log the IOException here…
                 }
     }
}

About Memory Considerations

The action controller class calls the finalizers for both successful and failed scenarios. The finalizers that are not inside a For Each loop do not begin until the end of the action. The finalizers that are inside a For Each loop do not begin until the end of the loop. When a processor that implements the ProcessorFinalizer completes the execution, it is still in the scope of the action. The processor does not get purged by the garbage collector to release the memory.

If a processor implements the ProcessorFinalizer, it is a good practice to limit the number of member variables for that processor and ensure that the processor is not using a large amount of memory. If the processor uses a lot of memory, it is a good practice to release the memory as soon as it is no longer required. For example, if a processor is using a large HashMap, and it also implements the ProcessorFinalizer, the processor should clear the contents of the HashMap when it is done using it and assign the null pointer to this HashMap.