Simple Example

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 XNGR XML Browser 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 XNGR XML Browser desktop and add the example XML document as can be found in the examples to the XNGR XML Browser 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 XNGR XML Browser desktop and add the example XML document as can be found in the examples to the XNGR XML Browser 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 xngr 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.