An adapter is a class which implements the gran.app.adapter.Adapter interface. Each subsystem in TrackStudio has its own interface, inherited from gran.app.adapter.Adapter. For instance, to implement an export adapter, you must implement the class, which implements the gran.app.adapter.ExportAdapter interface. Adapters are stateless components, i.e. they do not have an internal state and do not remember the history of the previous calls. 

The list of the loadable adapters can be found in trackstudio.adapter.properties, for example:

# External adapters

adapter.export gran.app.adapter.export.XMLExportAdapter
adapter.email gran.app.adapter.email.BaseFilterNotifyAdapter

If you need to execute a pipeline of some adapters (implementing the same interface) to perform some operation, you must put them in one line using ';' as a separator, for example:

adapter.pop3 gran.app.adapter.pop3.BasePOP3Adapter;
             gran.app.adapter.pop3.MailImportMessagePOP3Adapter;
             gran.app.adapter.pop3.MailImportTaskPOP3Adapter;
             gran.app.adapter.pop3.CleanPOP3Adapter;
             gran.app.adapter.pop3.PostProcessingPOP3Adapter

If there are two identical adapters in the list, only the first of them will be executed. If there is an adapter not implementing the required interface in the list, it is not loaded. 

TrackStudio assumes each type of adapter as consists of three components: the adapter interface, the proper adapter, and AdapterManager establishing the pipeline. 

Let's look the implementation and interaction of the system components in the work of adapters:

1. Interface. The adapter interface must extend Adapter. The following requirements are demanded of the method signature:

• The name of the interface must be SomethingAdapter
• Every method must either throw GranException or not throw an exception.
• The names of methods must end with Impl
• If a method returns a value, this method must have a parameter result of a returning type, which must come last in the list of parameters. For example,

  public boolean authorizeImpl(User user,
                               String password,
                               boolean result)
                 throws GranException;

• Persistent objects (with rare exception) are passed either by their string identifier or in the collections java.util.Collection, java.util.LinkedList, etc. In the case of an ID passing of the object, to continue working you must open a Hibernate session and load the object. When using the object list you do not have to open a session (remember that in this case each object in the collection must be Hibernate-initialized). If executing an adapter results in changes in the persistent object, you must always open and close the session. It is also recommended that you use transactions in this case.

Interface example:

// $Id: OpenAPI.dtx,v 1.14 2004/05/31 13:49:10 maximkr Exp $
package gran.app.adapter.template;

import gran.app.adapter.Adapter;
import gran.exception.GranException;

public interface TemplateAdapter extends Adapter
{
    public String methodThatReturnSomethingImpl(String param,
                                                String result)
                  throws GranException;

    public void methodThatReturnNothingImpl(String param)
                throws GranException;
}

2. An adapter has the following structure:

// $Id: OpenAPI.dtx,v 1.14 2004/05/31 13:49:10 maximkr Exp $
package gran.app.adapter.template;

import gran.exception.GranException;
import gran.tools.Logger;

public class BaseTemplateAdapter implements TemplateAdapter
{
    private static Logger log = new
            Logger("gran.app.adapter.template.TemplateAdapter");

    public boolean init()
    {
        return true;
    }

    public String getDescription()
    {
        return "Base Template Adapter";
    }

    public String methodThatReturnSomethingImpl(String param,
                                                String result)
                  throws GranException
    {
        return param + " OK";
    }

    public void methodThatReturnNothingImpl(String param)
                throws GranException
    {
        return;
    }
}

Within an adapter, methods can be called only through AdapterManager. Direct calling *Impl-methods is not recommended as it may cause problems when enhancing the system.

3. SomeAdapterManager controls the lists of adapters supporting the defined interface and is responsible for the correct passing of the parameters. SomeAdapterManager may have the following structure:

// $Id: OpenAPI.dtx,v 1.14 2004/05/31 13:49:10 maximkr Exp $
package gran.app.adapter.template;

import java.util.Collection;
import java.util.Iterator;
import gran.exception.GranException;

public class TemplateAdapterManager
{
    private Collection am = null;

    public TemplateAdapterManager(Collection adapters)
    {
        am = adapters;
    }


    public String methodThatReturnSomething(String param)
                  throws GranException
    {
        String result = null;
        for (Iterator iter = am.iterator(); iter.hasNext();) {
            TemplateAdapter adp = (TemplateAdapter) iter.next();
            result = adp.methodThatReturnSomethingImpl(param, result);
        }
        return result;
    }

    public void methodThatReturnNothing(String param)
                throws GranException
    {
        for (Iterator iter = am.iterator(); iter.hasNext();) {
            TemplateAdapter adp = (TemplateAdapter) iter.next();
            adp.methodThatReturnNothingImpl(param);
        }
    }
}

The system enhancement is carried out through classes implementing the existing interfaces (for example, gran.app.adapter.ExportAdapter). At the same time, you do not have to modify the initial system code, the adapter interface, or AdapterManager. 

To call the adapters, a singleton class AdapterManager is used. This class stores the list of all adapters available on the system and allows registration of new adapters in the system. To call a method (e.g. for exporting), you must execute the following:

AdapterManager.getInstance().getExportAdapterManager()
                            .export(taskid, userid);