XCAT Logo

XCAT-Java Tutorial

Introduction

This is a tutorial for xcat-java users to be able to run the current set of examples available with the toolkit and to learn the steps required to develop new xcat-components. The CCA vocabulary, terminology and features have been described in this page. 

Requirements

  1. XCAT-Java needs Java 1.3. Java 1.4 cannot be used as some of our security libraries do not work with it. We are in the process of fixing this problem. Please monitor this space for more information.
  2. Packages needed by XCAT-Java that are distributed along with the tarball are:
    1. Ant (ant-1.51.jar, optional-1.51.jar, xercesImpl-220.jar, xml-apis-220.jar)
    2. Castor (castor-0.9.2.jar, xerces_2_0.jar)
    3. Jyton (jython-2.1.jar)
    4. CoG (cog-0.9.13.jar, cryptix.jar, iaik_javax_crypto.jar, iaik_jce_full.jar, iaik_ssl.jar, log4j-core-20020226.jar)
    5. WSDL (wsdl4j_0_8.jar)
    6. XSOAP (xsoap_1.2.25-B1.jar)
  3. You need to get the following packages as they are not distributed with XCAT-Java
    1.     Security packages
      1.     jcert.jar
      2.     jsse.jar
      3.     jnet.jar

Installing XCAT

  1. Download the XCAT tarball from here
  2. Unzip and untar (use gnu tar) the tarball into your directory.
    This directory is your XCAT_HOME. The jython scripts use this variable to get location of various files. This variable should be automatically set in the top level run.sh script.

Compiling XCAT-Java

  1. Unix/Linux

    1. At the top level directory
      ./make.sh
  2. Windows

    1. At the top level directory
      ./build

Simple Example

Now you can run a simple example. The simple example consists of two XCAT components that are instantiated and connected. Then a method is invoked on one of the components to get the computation started. The first component is a SimpleEchoGeneratorComponent and the other is SimpleEchoPrinterComponent. The code for the components can be found in  the following location: $(XCAT_HOME)/src/java/samples/.

SimpleEchoGeneratorComponent has one uses port and SimpleEchoPrinterComponent has one provides port. Both the ports are of the same type: http://www.extreme.indiana.edu/xcat/samples/wsdl#echo. (Please note that the type is represented as a url just so that it can be unique. This is similar to the the concept of uniqueness in XML namespaces. XML Namespaces do not guarantee that the namespaces point to anything. Please do not try to browse the given url for the type.) As a result these ports can be connected. SimpleEchoGeneratorComponent also has one provides port, GoPort, that is used to indicate to the component  that it can now invoke methods on its uses port. Note that the CCA does not mandate how ports should be used. Just for this example, we have designed the SimpleEchoGeneratorComponent to wait till it receives a call on its GoPort before invoking methods on its uses port.

These two components can be instantiated and connected using a jython script. The script for this example can be found in the following location: *(XCAT_HOME)/src/python/samples/simpleEcho.py. This script sets the environment for this example.

Debugging Level

XCAT uses the logger from xsoap for debugging. The script run.sh  for Unix/Linux and run.bat has examples of various debugging levels that can be set for XCAT. By default, no output is dumped on the screen. To obtain all debugging level is, the following line can be uncommented in the $(XCAT_HOME)/.run.sh script:

JAVA_OPTS="-Dlog=:ALL -Dsoaprmi.security.providers=jsse -DPYTHONPATH=./src/python/lib -DXCAT_HOME=$PWD

Running the Example

Unix/Linux 

Change directory to the $(XCAT_HOME) directory level, type the following command

.        ./run.sh script ./src/python/samples/stringPrinter.py 

Windows

Change directory to the $(XCAT_HOME) directory level, type the following command

.        run script src\python\samples\stringPrinter.py 

Expected Output

The following page shows  the expected output on stdout.

The prompt does not return as the process is still running. This is because the XCAT component with provides port are services that have to be explicitly brought down. You can use your OS specific way for killing this process. On Unix/Linux ^C works fine.

 

Stop the Components

EchoPrinterComponent must implement Component interface that has only one method to implement: setServices().


FAQs

  1. Question: The components used in this sample refer to some ports described in the XML file at address "http://www.extreme.indiana.edu/xcat/samples/wsdl". I can't find the web page with this url.
    Answer: The string "http://www.extreme.indiana.edu/xcat/samples/wsdl" refers to a namespace and just serves as a unique string that represents the port type. This is similar to XML namespaces. XML namespaces do not guarantee that the namespaces point to specific web pages.

  2. Question: What are the command line options to run XCAT components on Unix and Windows?
    Answer:
    Windows: run.bat script src\python\samples\simpleEcho.py
    Unix: run.sh script src\python\samples\simpleEcho.py

    These commands will allow you to launch the two component in the same address space. It is also possible to run the two components as two different processes on grid resources by using the following in the script:
    cca.setCreationMechanism(generator, "gram")

  3. Question: I have setup by hand the logger object in "SimpleEchoGeneratorComponent.java" with "logger.setLevel(Level.FINER)" and now the sample writes the echo string correctly. Is there a better/different way to do it?
    Answer: You can set logging level by setting it as a system property. If you use the provided run.bat/.sh script, set the environment variable JAVA_OPTS:
    on windows: set JAVA_OPTS=-Dlog=:ALL
    on linux (bash): export JAVA_OPTS=-Dlog=:ALL

    In general, use the syntax -Dlog=your.package:LEVEL
    The different possible values for levels are: FINEST,FINER and FINE. For more details please see: http://www.extreme.indiana.edu/~aslom/minilogger/v10/README.html.

    If you call java directly just pass -Dlog=.. argument.

  4. Question: Does XCAT work with GT3?
    Answer: We haven't tested XCAT with GT3 yet. We plan to do so soon. It currently works with CoG 0.9.X and GT 2.X

  5. Question: Do you use XML to automate component creation and connections?
    Answer: Yes, we do. An example can be found in xcat_2.0.2-RC1/src/xml/appman.xml and simple XSD schema for it in xcat_2.0.2-RC1\src\xsd

[Back to XCAT] [ IU CS ] [ Extreme! Computing ]
ccat@extreme.indiana.edu
Last modified: $Id: index.html,v 1.9 2003/08/01 23:11:19 mgovinda Exp $