Talon
An OpenPrivacy Java Component Framework

Developer Notes

Component creation

Talon uses a ComponentFactory ( see the Factory Design Pattern ) mechanism to create Components. Components are Objects that advertise their functionality by defining an interface and a standard set of methods that meet that interface. Talon developers code to the interface and not to a particular implementation. This allows dynamic (run-time) loading of component objects.

Polymorphism and interfaces

At its heart, a Talon component is a Java interface with a set of defined methods. This means that a given Component could actually implement multiple interfaces.

Example:

   Logger interface --- |
   Dump interface ----- |
                        |
                        | --- SimpleLogger implements Logger, Dump

In the above example, the SimpleLogger Component implements the Logger and Dump interfaces. This means that methods from the Dump interface and Logger interface can be used within the SimpleLogger.

This key feature of Talon component programming enables a developer to concentrate on designing clear, simple interfaces which can then be aggregated into larger components.

Initialization

When a Talon application starts up it looks for a properties file in certain locations (this is usually based on the project.

• The directory specified by the property: "user.home".
• The directory specified by the property: "java.home".
• /etc ( on unix-based systems )

This lookup mechanism can be overridden via the system property "talon.properties". It may be usefull to use a "resource:" URI via the ResourceMapper. A good example is loading Talon via a WAR application via "resource:/etc/talon.properties"

Example: java -Dtalon.project=sierra MyApplication

This example will launch a new Java Virtual Machine but the talon.project property will be overridden as "sierra".

The talon configuration file is a very simple format. If you require more advanced initialization for your components one of your properties could be a pointer at further information. This could be a URL to an XML document which provided an application specific configuration format.

Required Properties

When you deploy a Talon component it is sometimes necessary to associate a set of properties, a URL to obtain additional information, JDBC connection information, etc. Some of these may be required for the component to even function correctly. The Talon PropertyManager can help you with this.

Example:

    public static final String[] REQUIRED_PROPERTIES = { "nym_name" };

    public void init() throws TalonException {

        //require specific properties.  This should throw an Exception if the
        //properties aren't available.
        this.getComponentHandle().getInitProperties().require( REQUIRED_PROPERTIES );
    }

This will perform initialization within your component implementation. If the "nym_name" isn't provided within your component deployment descriptor, the component will throw an Exception within initialization and will not be used.

Coding Conventions and Best Practices

When designing a Talon application there is a set of general conventions that can make help to make Talon code clearer and thus easier both to code and to understand. Some of these are listed here.

• It is a bad idea (although possible) to pull a Component based on its implementation classname. If you want to obtain a specific implementation try the following:

        ComponentFactory.getInstance( MyClass.class );
        

  This enables a compile time check to ensure that the given class is available. If you just enter the string it may throw a ClassNotFoundException sometime in the future.
• It's good practice to obtain a component via its talon_name property. Further, this mechanism provides for the specification of additional component properties.

URIs

Component Names:

Refer to a component by name.

talon://

this is a talon URI

/component-name

This URI is a Component Name

/product

what follows is the product name this component belongs to.

/default

this uses a product name of "default"

/name

a short name for the Component will follow

/logger

uses a short name of "logger"

Component References:

Every component instance within Talon has a unique URI called a component reference. This reference can be used to uniquely refer to an object instance.

Type References:

Every component within Talon has a unique URI called a type reference. This URI does not have any specific component instance information within it.

talon://

this is a talon URI

/type-reference

It is a TypeReference

/component

this URI describes a component

/org.openprivacy.sierra.query.talon.implementations.PropertyManagerTargetedQuery

the implementation class name.

/interface

notes an interface that this component implements.

/talon.components.PropertyManager

the interface class name.

Examples

Talon ships with some classes in the talon.implementations package which can be used as examples for creating new Components.

The following code will attempt to get Components based on a handle, their implementation and their name.

        //Get a PropertyManager Component via its handle in ComponentFactory
        PropertyManager pm = (PropertyManager)ComponentFactory
            .getInstance( ComponentFactory.TALON_DEFAULT_PROPERTY_MANAGER );

        //test the logging mechanism
        pm.getLogger().message( "It worked..." );

        //try to get a Component by its implementation
        ComponentFactory.getInstance( HandleManager
                                      .byImplementation( "talon.implementations.SimpleLogger" ) );
        
        //try to get a Component via its name
        ComponentHandle handle = HandleManager.byName( "talon:///component-name/product/default/name/logger" );
        ComponentFactory.getInstance( handle );