If you want to use this for standard EUROGRID resource brokering or
GT2- or GT3-enabled resource brokering, follow the instructions for
version 1.4 of the broker.

GETTING THE RESOURCE BROKER WORKING AS A WEBSERVICE
===================================================

You need to set up two things:
  An NJS containing the interface module
  A WS hosting environment containing the broker core

YOU MUST GET THE COUPLING BETWEEN THESE TWO CORRECT OR NOTHING WILL
WORK AT ALL.


Setting Up the Interface Module
-------------------------------

You need to put the broker JAR file on the NJS's classpath, but you
also need a whole bunch of JARs from the Pallas webservice gateway.
I've never narrowed down which ones are critical; I just add them all.

Your BROKER section from the IDB should be something like this (a copy
of the configuration in use at Manchester):

  BROKER org.uom.arcon.njs.broker.ws.BrokerNJSIfc [
    <broker xmlns="http://www.eurogrid.org/grip/broker/wsconfig"
            self="http://localhost:8085/axis/services/UnicoreServer"
            provider="http://localhost:8090/axis/services/Broker"
            ttl="600000">
      <qos user="unicore">/home/unicore/unicore/queuecheck</qos>
      <service
            config="/home/zzcgudf/unicore/NJS/conf/GRIPBroker_WS/wshe.config"/>
    </broker>
  ]

The self attribute says what we publish ourselves as as a Webservice,
which is required so the Broker can contact us back to get QoS data,
etc.

The provider attribute names the Broker webservice that is going to do
the bulk of the work.

The ttl attribute says how long (in milliseconds) delegated QoS and
Resource Checks have before they become uninteresting.  Shorter values
reduce the bad effects of unresponsive brokers, but might cause offers
to be missed if a broker is just busy.

The qos element describes the script that gets QoS data from the TSI,
with the user attribute saying the default identity to use for the
task.

The service element's config attribute says where to load the
configuration file for the Pallas webservice gateway code.  (Note that
we're not using the code to set up a gateway.)  The contents of that
file are:

  <server>
    <port listen="8085"/>
    <ssl usessl="false"/>
    <logdir file="/home/zzcgudf/unicore/NJS/conf/GRIPBroker_WS/logs"/>
    <watchdog delay="30000" period="3600000" mail="false"
        mailto="donal.k.fellows@man.ac.uk"/>
    <threads number="10"/>
  </server>

This starts the server on port 8085, doesn't use SSL to secure it (not
a great long-term choice, but good for demonstration purposes), sets
up the logging and a watchdog task, and configures the size of the
thread pool.  I think.


Setting Up the Broker Webservice
--------------------------------

First, make sure you have Apache Tomcat (servlet container) and Apache
Axis (webservice engine).  Make sure that Tomcat will start on the
correct port (in the demonstration configuration, that is port 8090)
by specifying the correct bit in Tomcat's server.xml (it is set in a
Connector element's port attribute.)

Then add uombroker.jar, ajo.jar and njs.jar to the axis lib directory
(no classpaths need modifying as the Axis engine picks this up
automatically).  The lib directory is probably
CATALINA_HOME/webapps/axis/WEB-INF/lib (where CATALINA_HOME is the
place where Tomcat was installed.)

In the same directory as uombroker.jar, create a file called
Broker.config with contents something like this:

  <config xmlns="http://www.eurogrid.org/grip/broker/ws">
    <master handle="http://localhost:8085/unicore/services/UnicoreServer"
            vsite="unicore://maisie.mvc.mcc.ac.uk:4433/GRIPBroker_WS/" />
    <offer validityPeriod="1"/>
    <delegate>
      <!-- No delegation -->
    </delegate>
  </config>

The master element has two attributes:

  handle is a reference to the NJS interface module defined above

  vsite is the name of the Vsite for which we generate offers; the
  format is mostly self-explanatory (host and port describe the Usite,
  the path fragment gives the name of the Vsite within the Usite.)

The offer element allows control (via the validityPeriod attribute,
which is in hours) over how long tickets are valid for.

The delegate element contains a collection of vsite elements, each of
which has a vsite attribute (formatted exactly like the vsite
attribute of the master element) to which this broker will delegate
requests.  The above configuration does not delegate at all, as the
delegate element has empty content (the comment doesn't count.)

Now, you are ready to start Tomcat.  (The start_tomcat shell script is
useful for this.)  The first time you start Tomcat, you need to deploy
the broker into the Axis container.  THIS ONLY NEEDS TO BE DONE ONCE.
To deploy the broker, you will need the following in a wsdd document:

  <deployment
      xmlns="http://xml.apache.org/axis/wsdd/"
      xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
    <service name="Broker" provider="java:RPC" style="rpc" use="encoded">
      <parameter name="wsdlTargetNamespace"
          value="http://www.eurogrid.org/grip/broker/"/>
      <parameter name="wsdlServiceElement" value="BrokerService"/>
      <parameter name="wsdlServicePort" value="Broker"/>
      <parameter name="className"
          value="org.uom.arcon.njs.broker.ws.BrokerSoapBindingSkeleton"/>
      <parameter name="wsdlPortType" value="Broker"/>
      <parameter name="allowedMethods" value="*"/>
      <parameter name="scope" value="Application"/>
      <typeMapping
          xmlns:ns="http://interfaces.njs.arcon.fujitsu.com"
          qname="ns:ResourceCheckerException"
          type="java:com.fujitsu.arcon.njs.interfaces.ResourceCheckerException"
          serializer="org.apache.axis.encoding.ser.BeanSerializerFactory"
          deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory"
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
    </service>
  </deployment>

Use your favourite Axis deployment technology to do this, as detailed
on the Axis website.  I admit to having forgotten how to actually do
this though; as I said, it only needs doing once.