Developing from the NEESPOP distribution

Developing with the NEES-POP Distribution

Assumptions and requirements

This page will assume you are developing on a Unix-based platform, such as Linux or Mac OSX. Windows should be quite similar, but I have not tested it. Furthermore, I will assume that we are working in $HOME/code, e.g. /home/hubbard/code

Installing from the NEESGrid Distribution

The NEESGrid software can always be downloaded from www.neesgrid.org/software. For this document, I will use release 3.0. Documentation on installing it can be found at www.neesgrid.org/documents. That installation is beyond the scope of this document.

By default, the installation goes into /usr/local/nees, and I will assume that this is your location as well. The code, as shipped, already has NTCP built and deployed into /usr/local/nees/opt/grid, so you don't need to edit the WSDD files yet.

You will still need to download nclient into $HOME/code, as it's not part of the SI distribution yet.

For more information on the NEESGrid CVS archive, please see www.mcs.anl.gov/neesgrid/cvs.html Please note that you do not need CVS commit access to download and compile the code, and the examples below use anonymous read access. Commit access is only required if you are an author of SI-distributed code.

To compile and run code, we need the following:

The Globus Toolkit, core only (pure java binaries). See http://www-unix.globus.org/toolkit/download.html I will use version 3.2 in my examples. In version 3.2, that's http://www-unix.globus.org/ftppub/gt3/3.0/3.2/gt3.2-core-bin.tar.gz
NTCP plugins from CVS, package name 'ntcp_plugins'
My example code from CVS, package name 'nclient'
Supporting tools (As noted in the NEESGrid documentation), including Ant, Java 1.4.2 or later, etc.

Installing Java and Ant

Most operating systems do not include Java by default, due to licensing issues. (Mac OSX is an exception). The Sun pages are a bit confusing, but you want the SDK (Software development kit) not the JRE (java runtime environment). The JRE-only download doesn't have the bits required to compile code, and we definitely want to compile.

To get Java, go to http://java.sun.com/ and select Downloads. You want 'Java 2 platform, standar edition tools (J2SE)'. This documentation was produced using version 1.4.2; version 1.5 is likely to have bugs and is not yet recommended. Follow the Java install instructions, and make sure (as explained below) that JAVA_HOME and PATH are set correctly. By default, it installs into

/usr/java/{version}

I usually create a symlink, so that I have

/usr/java/current

as JAVA_HOME. You can do this with
ln -s /usr/java/{version} /usr/java/current

Apache Ant is a Java build tool, more or less equivalent to Make. You can download it from http://ant.apache.org/bindownload.cgi. It usually installs into

/usr/local/apache-ant-{version}

You will need to set the ANT_HOME variable to match this, and add ANT_HOME/bin to your path. Make sure that

ant -version

works before proceeding.

Environment Variables

Many of the build tools depend on environment variables being set correctly to function. The procedure to do so depends on your login shell. These examples work for csh or tcsh. If you prefer bash, replace 'setenv' with 'variable=value; export VARIABLE' and it should work.

OGSA_ROOT

Add the following to your .cshrc:

setenv OGSA_ROOT /usr/local/nees/opt/grid

JAVA_HOME

Depending on your setup, you may also need to set JAVA_HOME. To test this, try

echo $JAVA_HOME

On Mac OSX 10.3.2, JAVA_HOME is automatically set to

/Library/Java/Home

If you get

tcsh: JAVA_HOME: Undefined variable.

then you'll need to set JAVA_HOME to match where you installed Java. On RedHat v9, I have

setenv JAVA_HOME /usr/java/j2sdk1.4.1_03

in my .cshrc.

ANT_HOME

Ant also needs to know where its installed. On RedHat v9, I have

setenv ANT_HOME /usr/local/apache-ant-1.5.4

On Mac OSX, I have Ant installed via Fink, which sets JAVA_HOME to

/sw/lib/ant/

PATH

Once you have the environment variables set, you may need to add them into your path. To test this, try the following:

which ant

which javac

Both should be found. If not, add something like this to your .cshrc:

setenv PATH $ANT_HOME/bin:$JAVA_HOME/bin:$PATH

You can verify the ant version by running

ant -version

and verify that you have at least version 1.6.1. For example:

Apache Ant version 1.6.1 compiled on February 12 2004

You can check the Java version by running

java -version

Verify that it's at least version 1.4.2, e.g.

java version "1.4.2_03"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_03-117.1)
Java HotSpot(TM) Client VM (build 1.4.2-34, mixed mode)

CVSROOT and CVS_RSH

If you read the CVS page, you'll have already done this. Otherwise, you need

setenv CVSROOT :pserver:anonymous@neescvs.mcs.anl.gov:/disks/cvs/neesgrid

setenv CVS_RSH ssh

to point to the CVS server.

Downloading client and plugins from CVS

Once you have the environment variables set, change directories into $HOME/code, and do the following:

cvs checkout ntcp_plugins nclient

This will create a directory tree like this:

$HOME/code -> ntcp_plugins/
              nclient/

Test #1: Start up NTCP with the Dummy Plugin

When you deploy NTCP, Ant takes the 'service description' in $HOME/code/NTCP/server/ntcp-server-config.wsdd, and merged it into the global $OGSA_ROOT/server-config.wsdd file. Let's take a closer look at this step, as it has implications we need to understand as NTCP authors. (This was done for you when the NEES-POP distribution was built. To do it yourself, see the instructions on the 'developing from CVS' page.)

Here are the contents of the file:

<?xml version="1.0" encoding="UTF-8"?>
<deployment name="defaultServerConfig" xmlns="http://xml.apache.org/axis/wsdd/" 
            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"
            xmlns:gsdl="http://www.gridforum.org/namespaces/2002/10/gridServices"
            xmlns:globus-properties="http://types.ogsa.globus.org/properties_detail"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 <service name="nees/ntcp/NTCPServer" provider="Handler" style="wrapped">
    <parameter name="name" value="NTCP Server"/>
    <parameter name="schemaPath" value="schema/nees/ntcp/ntcp_server_service.wsdl"/>
    <parameter name="className" value="org.nees.ntcp.ntcpServer.NtcpServer"/>
    <parameter name="baseClassName" value="org.nees.ntcp.server.impl.NtcpServerImpl"/>
    <parameter name="operationProviders" value="org.globus.ogsa.impl.ogsi.NotificationSourceProvider"/>
    <parameter name="handlerClass" value="org.globus.ogsa.handlers.RPCURIProvider"/>
    <parameter name="persistent" value="true"/>
    <parameter name="allowedMethods" value="*"/>
    <parameter name="isSecure" value="false"/>
    <parameter name="authorization" value="none"/>
    <parameter name="isProfiling" value="false"/>
    <parameter name="ntcpBackendFactory" value="org.nees.ntcp.server.backend.test.DummyControlFactory"/>
    <parameter name="localPolicyPlugin" value="org.nees.ntcp.server.backend.test.DummyLocalPolicyPlugin"/>
 </service>

 </deployment>

The line of interest is near the end:

    <parameter name="ntcpBackendFactory" value="org.nees.ntcp.server.backend.test.DummyControlFactory"/>

This defines which NTCP plugin gets called when NTCP runs. The default as shown uses the dummy control plugin. When we want to change to another plugin, we have to

Change the ntcp-server-config.wsdd
Redploy
Restart the NTCP

Edit the (deployed already) $OGSA_ROOT/server-config.wsdd
Restart NTCP

Method two is quicker and easier, but has one gotcha to beware of: Redploying will overwrite any changes you have made.
Note that, once the container is started, the server-config.wsdd file is not re-read, so you can safely edit it once a container is up and running.

For now, we'll leave the WSDD files at their default values, and proceed to starting up our first NTCP container.

Running an NTCP server

The following commands should start an NTCP container (grey box in the introductory diagram) with the dummy control plugin on port 8090:

cd /usr/local/nees/opt/grid

and then

ant startContainer -Dservice.port=8090

Of course, you'll need to be logged int the machine with NTCP installed! You should see something like the following:

Buildfile: build.xml

startContainer:

startContainer:
     [java] [03/15/2004 17:05:46:182 ] org.globus.ogsa.server.ServiceContainer [run:569] INFO: Starting SOAP server at: http://140.221.11.87:8090/ogsa/services/ 
     [java] With the following persistent services:
     [java]  
     [java] http://140.221.11.87:8090/ogsa/services/nees/ntcp/commandBufferService
     [java] http://140.221.11.87:8090/ogsa/services/nees/ntcp/NTCPServer
     [java] http://140.221.11.87:8090/ogsa/services/core/admin/AdminService
     [java] http://140.221.11.87:8090/ogsa/services/core/management/OgsiManagementService
     [java] http://140.221.11.87:8090/ogsa/services/core/registry/ContainerRegistryService
     [java] http://140.221.11.87:8090/ogsa/services/core/jmsadapter/JMSAdapterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/core/logging/OgsiLoggingService
     [java] http://140.221.11.87:8090/ogsa/services/core/notification/httpg/NotificationSubscriptionFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/registry/VORegistryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/secure/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/notification/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/encoded/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/persistent/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/basic/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/delegation/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/routable/MasterRedirectedCounter
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/routable/LocalCounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/generate/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/deactivation/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/soap-secure/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/counter/logging/CounterFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/exception/ExceptionFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/notification/SinkListenerFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/complex/NestedArrayFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/complex/NestedFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/weather/WeatherFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/serialization/SerializationService
     [java] http://140.221.11.87:8090/ogsa/services/samples/google/GoogleSearchFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/any/AnyFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/servicedata/ServiceDataService
     [java] http://140.221.11.87:8090/ogsa/services/samples/array/ArraySampleFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/samples/chat/ChatFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/ogsi/NotificationSubscriptionFactoryService
     [java] http://140.221.11.87:8090/ogsa/services/ogsi/HandleResolverService
     [java] http://140.221.11.87:8090/ogsa/services/gsi/AuthenticationService
     [java] http://140.221.11.87:8090/ogsa/services/gsi/SecureNotificationSubscriptionFactoryService

Note that an interrupt signal (usually Control-C) will stop the container.

It's generally a good idea to redirect the output of the container to a logfile, so that you have a permanent record, and can view it from another login. Something like the following (C shell):

nohup ant startContainer -Dservice.port=8090 >& ntcp-logfile.txt &

Message Logging From the Dummy Plugin

You'll notice that the dummy plugin doesn't print anything out, so it's hard to debug. Go to $OGSA_ROOT and edit ogsilogging.properties, adding the following line:

org.nees.ntcp.server.backend.test.DummyControlPlugin=console,debug

(If you installed from the distribution, there are two copies of ogsilogging.properties, which is rather confusing. $OGSA_ROOT has the deployed version, and /usr/local/nees/opt/ogsa has the source. You need to edit the copy in $OGSA_ROOT.)

This will print brief messages upon receipt of NTCP commands. Here's an example:

     [java] [07/30/2004 12:40:32:615 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [openSession:34] DEBUG: openSession
     [java] [07/30/2004 12:40:35:329 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [propose:56] DEBUG: propose
     [java] [07/30/2004 12:40:37:335 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [propose:66] DEBUG: accepting transaction TR-393531744
     [java] [07/30/2004 12:40:37:413 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [execute:74] DEBUG: execute
     [java] [07/30/2004 12:40:39:563 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [getControlPoint:113] DEBUG: getControlPoint
     [java] [07/30/2004 12:40:39:611 ] org.nees.ntcp.server.backend.test.DummyControlPlugin [closeSession:45] DEBUG: closeSession

Building and Running the Example NTCP client

Once you have the NTCP server and dummy plugin running, it's time to run the client itself. As supplied, nclient does the following:

Opens a connection to the NTCP server
Propose moving ControlPoint 'ANCO' +10.0 units in the X direction, in displacement mode.
Execute the proposed move
Query the state of the control point
Close the connection and exit

(The example debug output above is from an nclient run, so you can see how it should appear when you run it.)

A word about Ant and build.xml

Much of the heavy lifting in building and running this code is supplied by Apache Ant, which does things like

reading environment variables (OGSA_ROOT, for example) and using them in the build
setting CLASSPATH - this is very hard to do by hand
selecting the class name to run

More information on Ant is best gotten from the O'Reilly Ant book.

Running nclient

If you are in machine configuration one above, with NTCP on the same machine, proceed to running nclient. I'm working on adding command line arguments, for now you'll have to edit source code to change the NTCP server machine.

To run nclient:

cd $HOME/code/nclient
ant run

Which should produce output something like the following - yours will differ, as this is an in-progress version that still has bugs.

Buildfile: build.xml

checkOGSA:

prepare:

compile:
    [javac] Compiling 1 source file to /Users/hubbard/code/nclient/build/classes

jar:
      [jar] Building jar: /Users/hubbard/code/nclient/build/lib/nclient.jar

run:
     [java] Opening connection to NTCP server at http://localhost:8090/ogsa/services/nees/ntcp/ in non-secure mode
     [java] Connection opened OK, now sending openSession
     [java] - Logging is working
     [java] - Date: Fri Jul 30 12:40:34 PDT 2004
     [java] - Version: Apache-XML-Security-J 1.0.4
     [java] Proposing transaction #15437 id: TR-393531744
     [java] Transaction proposal accepted. Excellent.
     [java] Executing move, may take 60-90 seconds
     [java] Execute completed; looping until transaction completes
     [java] Move complete; transaction terminated
     [java] Querying the control point
     [java] Control point name: dummy
     [java] Control point param1: 1.0
     [java] Control point param2: 2.0
     [java] Closing NTCP session
     [java] Done.

BUILD SUCCESSFUL
Total time: 22 seconds

You are now ready to proceed to the next page, a walk through the nclient source code.