eXchaNGeR v08
www.xngr.org
SourceForge Logo

Service Development

Simple Example (deprecated)

To start developing a new service can be very simple, for a service that displays "Hello World [arguments]" on the command-line when opened from the desktop, just follow the next steps:

Step 1:

Create the file SimpleService.java and copy the next code in there:

import org.xngr.*;

public class SimpleService extends XService {
  public void open( String[] arguments) {
    System.out.println( "Hello World: ["+arguments[0]+"]");
  }

  public boolean close() {
    return true;
  }

  // Does not register an action with any element-type
  public XAction[] getActions( XElementType type) { return null;}

  // Is not associated with an element-type
  public void open( XElement element) {}
  public XDecorator getDecorator( XElementType type) { return null;}
}

Step 2:

Compile the java file and make sure that xngr.jar file is included in the classpath.

Step 3:

Create a service.xml file that needs to contain the following elements:

<service-description xmlns="urn:xngr.org:service.v01">
  <title>Simple Service</title>
  <description>The Simple Service Description</description>
  <argument>Arguments</argument>
  <icon>/icons/SimpleIcon.gif</icon>
  <author>Author</author>
  <reference>Website</reference>
  <version>01</version>
  <copyright>Copyright (c) 2002 Author</copyright>
  <service>SimpleService</service>
</service-description>

Note: for a complete description and to verify the service.xml file, see the service-description.dtd file, this file can be found in the installation directory.

Step 4:

Create an icon for the service!

Step 5:

Jar everything correctly together in a .jar file.
Use the command-line: 'jar cvf simple.jar .'

The directory structure for the simple.jar file should look like this:
/service.xml
/meta-inf/Manifest.mf
SimpleService.class
icons/SimpleIcon.gif
...

Step 6:

Add the simple service to the eXchaNGeR desktop.

An example service like this together with the sources can be found in the service examples downloads.

Associated Service Example

A Service can associate itself with a specific element-type, this can also be done very easily, as the next steps will show. The bold parts are used to highlight the differences from the simple example.

Step 1:

Create the file AssociatedService.java and copy the next code in there:

import org.xngr.*;

public class AssociatedService extends XService {
  // Creates an element-type as used by the examples.
  private static final ElementType ADDRESS_TYPE = 
      new XElementType( "address", "urn:xngr.org:example.address.v01");
  private AddressDecorator addressDecorator = null;
  
  public AssociatedService() {
    // Create the initial Decorator
    addressDecorator = new AddressDecorator();
  }

  public void open( String[] arguments) {
    System.out.println( "Hello World: ["+arguments[0]+"]");
  }

  public boolean close() {
    return true;
  }

  // Does not register an action with any element-type
  public XAction[] getActions( XElementType type) { return null;}

  public void open( XElement element) {
    System.out.println("Hello World: "+element);
  }
  
  public XDecorator getDecorator( XElementType type) { 
    if ( type.equals( ADDRESS_TYPE)) {
      return addressDecorator;
    }
    return null;
  }
}

Step 1.1:

Create the file AddressDecorator.java and copy the next code in there:


import org.xngr.*;

public class AddressDecorator implements XDecorator {
  private ImageIcon icon = null;

  public AddressDecorator() {
    // Load the icon for the decorator
    icon = new ImageIcon( 
            getClass().getResource( "/icons/AddressIcon.gif"));
  }

  public String getName( XElement element) {
    // Get the information for the name out of the element.
    return element.getElement( "firstname").getValue()+" "+
              element.getElement( "lastname").getValue();
  }

  public String getDescription( XElement element) {
    // Discard the element and just return the String.
    return "Example Address";
  }

  public ImageIcon getIcon( XElement element) {
    // Discard the element and just return the icon.
    return icon;
  }
}

Step 2:

Compile the java files and make sure that xngr.jar file is included in the classpath.

Step 3:

Create a service.xml file that needs to contain the following elements:

<service-description xmlns="urn:xngr.org:service.v01">
  <title>Simple Associated Service</title>
  <description>The Simple Associated Service Description</description>
  <argument>Arguments</argument>
  <icon>/icons/SimpleAssociatedIcon.gif</icon>
  <author>Author</author>
  <reference>Website</reference>
  <version>01</version>
  <copyright>Copyright (c) 2002 Author</copyright>
  <service>AssociatedService</service>
  <element-type>
    <localname>address</localname>
    <namespace>urn:xngr.org:example.address.v01</namespace>
  </element-type>
</service-description>

Note: for a complete description and to verify the service.xml file, see the service-description.dtd file, this file can be found in the installation directory.

Step 4:

Create an icon for the service and create an icon for the decorator!

Step 5:

Jar everything correctly together in a .jar file.
Use the command-line: 'jar cvf associated.jar .'

The directory structure for the associated.jar file should look like this:
/service.xml
/meta-inf/Manifest.mf
AssociatedService.class
AddressDecorator.class
/icons/SimpleAssociatedIcon.gif
/icons/AddressIcon.gif
...

Step 6:

Add the simple associated service to the eXchaNGeR desktop and add the example XML document as can be found in the examples to the eXchaNGeR explorer.

Action Service Example

A Service can add an action to an element-type, as the next steps will show. The bold parts are used to highlight the differences from the simple example.

Step 1:

Create the file ActionService.java and copy the next code in there:

import org.xngr.*;

public class ActionService extends XService {
  // Creates an element-type as used by the examples.
  private static final ElementType ADDRESS_TYPE = 
      new XElementType( "address", "urn:xngr.org:example.address.v01");
  private XAction[] actions = null;
  
  public ActionService() {
    // Create the initial Action
    actions = new XAction[] { new AddressAction() };
  }

  public void open( String[] arguments) {
    System.out.println( "Hello World: ["+arguments[0]+"]");
  }

  public boolean close() {
    return true;
  }

  public XAction[] getActions( XElementType type) { 
    if ( type.equals( ADDRESS_TYPE)) {
      return actions;
    }

    return null;
  }
  
  // Is not associated with an element-type
  public void open( XElement element) {}
  public XDecorator getDecorator( XElementType type) { return null;}
}

Step 1.1:

Create the file AddressAction.java and copy the next code in there:


import org.xngr.*;

public class AddressAction implements XAction {
  private ImageIcon icon = null;

  public AddressAction() {
    // Load the icon for the decorator
    icon = new ImageIcon( 
            getClass().getResource( "/icons/AddressIcon.gif"));
  }

  public void execute( XElement element) {
    System.out.println("Hello World ["+element+"]");
  }

  public boolean isEnabled( XElement element) {
    // Always enabled.
    return true;
  }

  public String getName() {
    return "Address Action";
  }

  public String getDescription() {
    return "An example action for the example address element.";
  }

  public ImageIcon getIcon() {
    return icon;
  }
}

Step 2:

Compile the java files and make sure that xngr.jar file is included in the classpath.

Step 3:

Create a service.xml file that needs to contain the following elements:

<service-description xmlns="urn:xngr.org:service.v01">
  <title>Simple Action Service</title>
  <description>The Simple Action Service Description</description>
  <argument>Arguments</argument>
  <icon>/icons/SimpleActionIcon.gif</icon>
  <author>Author</author>
  <reference>website</reference>
  <version>01</version>
  <copyright>Copyright (c) 2002 Author</copyright>
  <service>ActionService</service>
  <service>ActionService</service>
  
</service-description>

Note: for a complete description and to verify the service.xml file, see the service-description.dtd file, this file can be found in the installation directory.

Step 4:

Create an icon for the service and create an icon for the action!

Step 5:

Jar everything correctly together in a .jar file.
Use the command-line: 'jar cvf associated.jar .'

The directory structure for the associated.jar file should look like this:
/service.xml
/meta-inf/Manifest.mf
ActionService.class
AddressAction.class
/icons/SimpleActionIcon.gif
/icons/AddressIcon.gif
...

Step 6:

Add the simple action service to the eXchaNGeR desktop and add the example XML document as can be found in the examples to the eXchaNGeR explorer.

Service Extension Example

A Service can be extended with external packages. This allows the 'service-developer' to specify a 'classpath' for the service.

The jar files specified as extensions can access:
- the classes for the service,
- other jar files specified as an extension for the same service,
- the exchanger classes,
- the classes defined on the classpath.

An extension can be defined by specifying the relative paths to the extension .jar files in the service.xml file:

<service-description xmlns="urn:xngr.org:service.v01">
  <title>Extension Service</title>
  <description>The Extension Service Description</description>
  <argument>Arguments</argument>
  <icon>/icons/SimpleExtensionIcon.gif</icon>
  <author>Author</author>
  <reference>website</reference>
  <version>01</version>
  <copyright>Copyright (c) 2002 Author</copyright>
  <service>ExtensionService</service>
  <extension>lib/extension.jar</extension>
  <extension>../extension2.jar</extension>
</service-description>

Note: for a complete description and to verify the service.xml file, see the service-description.dtd file, this file can be found in the installation directory.

Security

The services need to be able to run in a secure environment, therefor a Securtiy Manager has been installed this Security Manager does not allow a service to:
- call System.exit(),
- install a SecurityManager,
- override system classes.

To change the overall security for your machine please edit the policy file. You can find this file in the installation directory.


<<< Contents


Copyright © 2002, Cladonia Ltd.