Index Changes
View Attach (6) Info

Table of Contents

IEP Administration

Introduction

IEP Administration services provides a way to access the IEP service engine at runtime. It enables user to access information about, debug and modify a deployed process.

It is a part of Systemic qualities efforts. A collection of MBeans that interacts with IEP service engine and an IEP Management Services that exposes calls to these beans through a simple Java API.

The following actions can be performed using IEP Management Services.

  • Runtime view of an IEP Engine
    • Get the list of deployed IEP processes in a service unit.
    • Get the list of operators in a deployed IEP process.
    • Get the list of Attributes, of an operator in a deployed IEP process, exposed by IEP Service Engine.
  • Debugging
    • Attach a step by step debugger to an IEP process.
    • Invoke various debug commands on the IEP process.
    • Get current debug information available with debugger for any operator.
    • Detach the step by step debugger from an IEP process.
  • Runtime modification to IEP Engine
    • Add a data access object to an operator in a deployed IEP process.
    • Remove the data access object.
    • Add a Save Stream operator for an Input Stream operator.
    • Remove the Save Stream operator.
    • Change operator properties. (Currently, only the WHERE clause of the Stream Projection And Filter operator can be modified.) For more information, see Changing the Properties of an IEP Operator at Runtime.

Downloads

There are two main components.

How To Use

Command Line Client

Command line client is a reference application that uses APIs from IEP management services.

  • Download the IEPManagementService.jar file from the above mentioned location.
  • Download the IEP Management Client jar file.
    • If you downloaded the project with complete source code, open the project in NetBeans, add the IEPManagementServices.jar file to the project class path if it is not added already.
    • Add jbi-admin-common.jar to the class path as well. The usual location of this jar file is GlassFish-installation-dir\jbi\lib
    • Build the project and run the generated jar file which should be same as IEPManagement.jar.
  • If you downloaded just the runnable jar file, add the IEPManagement.jar, IEPManagementServices.jar and jbi-admin-common.jar from GlassFish Installation dir\jbi\lib to class path and use the following command to start the client console. 
java com.sun.esb.management.client.tester.IEPManagementSample

To get the list of available commands and the required parameters, type h or help on the console, or see the IEP Management Services Client section.

IEP Management API or build custom client

IEP Management API is a wrapper around MBean calls to Administration bean in IEP Service Engine. If you plan to create your own client application using the APIs, then add this jar file and jbi-admin-common.jar from \jbi\lib to your project class path. The IEP Management Client(info) can be used as reference implementation.

For detailed description about the APIs, see the IEP Administration Services section.

Component Descriptions

IEP Management Services Client

The sample command line client uses the management services to execute methods on administration beans. By default, it connects to localhost 8686 using admin as the userID and adminadmin as the password. To change, use the connect command.

To run the client, call: 

java com.sun.esb.management.client.tester.IEPManagementSample

Entering h or help will print the available commands and their parameters:

h, help: Prints this.

q, quit: Quit

connect host port userID password: Connect to management bean server. Default values are localhost 8686 admin adminadmin

li, listIEP service_unit_name : List IEP process deployed in a service unit. service_unit_name is the name of IEP unit that is deployed in jbi. Look for screen capture below to locate it in NetBeans server configuration. If no service unit name is provided, the command will list all deployed IEP plans.

d, debug plan_name : Debug an IEP process. The plan_name can be found using listIEP command. For more information, see the IEP Debugging section.

lo, listOperators plan_name : List operators in an IEP process. The plan_name can be found by using the listIEP command.

la, listAttributes plan_name operator_name : List visible properties of an operator. The operator_name can be found by using the listOperators command.

scs, startChangeSet : informs the IEP engine that a new change set request has been initiated. Refer Changing the Properties of an IEP Operator at Runtime.

acs, applyChangeSet : informs the IEP engine to schedule all the changes done by using changePropValue,cpv to be applied and persisted. After this for any further changes startChangeSet,scs must be called first. Refer Changing the Properties of an IEP Operator at Runtime.

ics, ignoreChangeSet : informs the IEP engine to ignore the change set. After this for any further changes startChangeSet,scs must be called first. Refer Changing the Properties of an IEP Operator at Runtime.

cpv, changePropValue plan_name operator_name attribute_key attribute_value : Set the value of a property. Refer Changing the Properties of an IEP Operator at Runtime.

eda, enableDA plan_name operator_name table_name : Enable Data Access for an operator into a table. For more information, refer Data Access wiki entry.

addss, addSaveStream plan_name operator_name jndi_name tableName : Add a save stream to an input stream operator. For more information, refer Save Stream. Returns the name of the Save Stream operator that is added.

rss, removeSaveStream plan_name save_operator_name : Remove the save stream operator. The save_operator_name is the name that gets returned by the addSaveStream operator.

You can find the service unit name for the listIEP command in the Services window of the IDE. Expand the Servers node, the GlassFish V2 node, the JBI node, the Service Assemblies node, and the individual service assembly node. See the following screen capture.

IEP Administration Services

API listing describes all the methods that are available with the latest IEP Service Engine.

To get a handle to IEPManagementService, use: 

IEPManagementServiceFactory.createNewServiceInstance(_MBeanServerConnection_object);

MBeanServerConnection can be obtained in many ways. One way is shown below. 

public static MBeanServerConnection getMBeanServerConnection(
      String urlString, String userName, String password)
      throws MalformedURLException, IOException {

   final JMXServiceURL url = new JMXServiceURL(urlString);
   String[] credentials = new String[] { userName, password };
   Map<String, String[]> environment = new HashMap<String, String[]>();
   environment.put("jmx.remote.credentials", credentials);
   final JMXConnector connector = JMXConnectorFactory.connect(url, environment);
   return connector.getMBeanServerConnection();

The URL String can be created using hostName and portNumber as 

String urlString = "service:jmx:rmi:///jndi/rmi://" + hostName + ":" + portNumber + "/jmxrmi";

IEP Debugging

There is a step by step IEP processor to facilitate some debugging for the IEP engine. The idea is to execute process in a per operator basis and let user control the flow. At every point of execution, user can get information related to any operator and its current state of data(events).

The steps are:

1. Call IEP Management services and set an IEP process for debugging by

a. calling setIEPForDebugging(mPlanName);. This will let the IEP engine know to attach a step by step processor to the process(plan).

b. or start the debug console using command line IEP Management Services Client use the command d, debug {plan_name}

2. Once an IEP process is attached to the step by step processor, user can execute debug commands by sending those commands through management services.

The list of debug commands that can be executed are:

help,h : Help on available commands.

quit,q : Quit the debug session and detach step by step processor.

next,n : execute next available operator.

completeCycle,cc : complete one cycle of IEP process.

nextCompleteCycles,ncc noOfTime(int) : complete cycles of IEP process noOfTime times.

nextCompleteCyclesForTimePeriod,nct milliseconds (long) : complete cycles of IEP process for milliseconds time.

addPauseBefore,apb operatorName : add a pause (breakpoint) before an IEP process.

nextTillPause,ntp : execute IEP process till a pause is found or cycle is complete.

nextOperator,no : display the name of the operator that is to be executed next.

removePauseBefore,rpb operatorName : remove the pause before the operator if there is one available.

listOperators,lo : List operator names in sequence of execution.It appends a '**' in front of operator names that are yet to be executed.

listOperatorProperties,lop operatorName : List all the properties associated with an operator.If operatorName is not provided the default will be used which is the last executed operator.

info,i : show the relevant information about the last executed operator.

info,i operatorName : show the debug information about the operatorName operator.

Go to IEP Wiki Home


G'day, Anonymous Guest

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-58) was last changed on 18-Nov-08 12:30 PM, -0800 by Jeff Stein