An adapter is a class realizing 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, realizing 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 realizing the required interface in the list, it is not loaded. 

TrackStudio takes each type of adapter as consisting of three components: the adapter interface, the proper adapter and AdapterManager realizing the pipeline. 

Let's take the realization 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 of a returning type named result, 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 a rare exception) are passed either by their string identifier or in the collections java.util.Collection, java.util.LinkedList, etc. To continue working in the case of the ID passing of the object, 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 to 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. The realization of 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 realizing 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 registering new adapters in the system. To call a method (e.g. for exporting), you must execute the following:

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