Skip Headers

Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3) B25386-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 20.3 Implement the Abstract Adapter Class

Implementing the `AbstractAdapter` class is optional. It is required only if you want to enable the user to create a data control by dragging and dropping a node onto the Data Control Palette. In this case, the dropped node represents the data source associated with the data control that you are creating. If you do not want this feature, you do not have to implement this class. For example, the CSV data control adapter that ships with JDeveloper does not implement this class because it does not support the drag-and-drop operation. Instead, this adapter displays a wizard to collect information from the user.

The simple CSV adapter implements the `AbstractAdapter`. When the user drags and drops a node onto the Data Control Palette, JDeveloper checks to see which adapter can handle the type of node that was dropped. You specify the node types that your adapter can handle in the `adapter-definition.xml` file. This file is used to register your adapter with JDeveloper. See Section 20.7, "Create an XML File to Define Your Adapter" for details about this file.

In your class, you have to implement some methods in the `AbstractAdapter` class, as described in these sections:

- Section 20.3.4, "Implementing the initialize Method"

- Section 20.3.5, "Implementing the invokeUI Method"

- Section 20.3.6, "Implementing the getDefinition Method"

## 20.3.1 Location of JAR Files

The abstract class `oracle.adf.model.adapter.AbstractAdapter` is located in the `JDEV_HOME/bc4j/lib/adfm.jar` file.

## 20.3.2 Abstract Adapter Class Outline

Example 20-1 shows an outline of a class that implements the `AbstractAdapter` class.

Example 20-1 Outline for Class That Implements AbstractAdapter

    import oracle.adf.model.adapter.AbstractAdapter;
    import oracle.adf.model.adapter.DTContext;
    import oracle.adf.model.adapter.AbstractDefinition;

    public class MyAdapter extends AbstractAdapter
    {
       public void initialize(Object sourceObj, DTContext ctx)
       {
          // you need to implement this method.
          // see Section 20.3.4, "Implementing the initialize Method".
       }

       public boolean invokeUI()
       {
          // you need to implement this method.
          // see Section 20.3.5, "Implementing the invokeUI Method".
       }

       public AbstractDefinition getDefinition()
       {
          // you need to implement this method.
          // see Section 20.3.6, "Implementing the getDefinition Method".
       }
    }

## 20.3.3 Complete Source for the SampleDCAdapter Class

Example 20-2 shows the complete source for the `SampleDCAdapter` class. This is the class that implements `AbstractAdapter` for the simple CSV adapter. Subsequent sections describe the methods in this class.

Example 20-2 Complete Source for SampleDCAdapter

    package oracle.adfinternal.model.adapter.sample;

    import java.net.URL;

    import oracle.adf.model.adapter.AbstractAdapter;
    import oracle.adf.model.adapter.AbstractDefinition;
    import oracle.adf.model.adapter.DTContext;

    import oracle.ide.Context;

    public class SampleDCAdapter extends AbstractAdapter
    {
       // JDev Context
       private Context              mJdevCtx    = null;

       // Source object of data
       private Object               mSrc        = null;
       // Source Location
       private String               mSrcLoc     = null;
       // data control name
       private String               mDCName     = null;
       // data control definition
       private AbstractDefinition   mDefinition = null;

       public SampleDCAdapter()
       {
       }

       /**
        * Initializes the adapter from a source object.
        * <p>
        * The source object can be different thing depending on the context of the
        * design time that the adapter is used in. For JDeveloper, the object will
        * be a JDeveloper node.
        * </p>
        * <p>
        * Adapter implementations will check the <code>"ctx"</code> parameter to
        * get the current design time context. The source object will be used to
        * extract the information for the data source.
        * </p>
        * @param sourceObj Object that contains information about the data source
        *            that will be used to define the data control.
        * @param ctx Current design time context.
        */
       public void initialize(Object sourceObj, DTContext ctx)
       {
          mSrc = sourceObj;
          mJdevCtx = (Context) ctx.get(DTContext.JDEV_CONTEXT);
       }

       /**
        * Invlokes the UI at the design time.
        * <p>
        * This method is a call back from the JDeveloper design time environment to
        * the adapters to bring up any UI if required to gather information about
        * the data source they represent.
        * </p>
        *
        * @return false if the user cancels the operation. The default retrun value
        * is true.
        */
       public boolean invokeUI()
       {
          // First check if this is a JDev environment.
          if (mJdevCtx != null && mSrc != null)
          {
             if (extractDataSourceInfo(mSrc))
             {
                SampleDCDef def = new SampleDCDef(mSrcLoc,mDCName);
                mDefinition = def;
                return true;
             }
             return false;
          }
          return false;
       }

        /**
        * <p>
        * The Definition instance obtained can be used by the ADF design time to
        * capture the data control metadata.
        *</p>
        *
        * @return The definition instance describing the data control design time.
        */
       public AbstractDefinition getDefinition()
       {
          return mDefinition;
       }

       /**
        * @param source the data source object.
        * @return false if data type is unknown.
        */
       public boolean canCreateDataControl(Object source)
       {
          return extractDataSourceInfo(source);
       }

       /**
        * Extracts information from a data source. This method extracts name
        * from the object.
        * @param obj the data source object.
        */
       private boolean extractDataSourceInfo(Object obj)
       {
          mDCName = "SampleDC";

          // See if the node dropped is a text node of CSV type.
          // We will assume that the CSV data file must end with .csv
          if (obj instanceof oracle.ide.model.TextNode)
          {
             oracle.ide.model.TextNode tn = (oracle.ide.model.TextNode) obj;
             URL url = tn.getURL();
             String loc = url.getFile();
             // Check if the file has a matching extension
             if (loc.endsWith(".csv"))
             {
                mSrcLoc = loc;
                String path = url.getPath();
                int index = path.lastIndexOf('/');

                if (index != -1)
                {
                   String fileName = path.substring(index+1);
                   int dotIndex = fileName.lastIndexOf('.');
                   mDCName = fileName.substring(0,dotIndex);
                }
                return true;
             }
          }
          return false;
       }

    }

## 20.3.4 Implementing the initialize Method

The framework calls the `initialize` method when the user drags and drops a node onto the Data Control Palette. The method has the following signature:

Example 20-3 initialize Signature

    public abstract void initialize(Object sourceObj, DTContext ctx);

The `sourceObj` parameter specifies the node that was dropped. You can check this to ensure that the node type is something your adapter can handle.

The `ctx` parameter specifies the design time context. The package path for DTContext is `oracle.adf.model.adapter.DTContext`.

In the `initialize` method, you should perform these tasks:

- check if the source node is something that you support

- if you support the node, then extract all the information that you need to create a data control instance from the source node. If the information is not sufficient to create a data control instance, you can display some UI in the `invokeUI` method to get the user to enter the required information.

For the simple CSV adapter, the `initialize` method simply sets some class variables. These class variables are checked later in the `invokeUI` method.

Example 20-4 initialize Method

       public void initialize(Object sourceObj, DTContext ctx)
       {
          mSrc = sourceObj;
          mJdevCtx = (Context) ctx.get(DTContext.JDEV_CONTEXT);
       }

## 20.3.5 Implementing the invokeUI Method

This method enables you to display any UI to collect information from the user about the dropped data source. The method has the following signature in the `AbstractAdapter`:

Example 20-5 invokeUI Signature

    public boolean invokeUI()
    {
       return true;
    }

The method should return `false` if the user cancels the operation in the UI. This means that the data control is not created.

The method should return `true` (which is the default implementation) if the UI was run to collect the information.

The simple CSV adapter uses the `initialize` method to call `extractDataSourceInfo`, which performs the following:

- checks that the node right-clicked by the user represents a text file and that the filename has a `.csv` extension

- gets the filename of the CSV file

- sets the `mSrcLoc` and `mDCName` class variables. `mSrcLoc` points to the location of the CSV file, and `mDCName` is the name used for the data control. In this case, it is just the name of the CSV file without the `.csv` extension.

  These variables are used by `invokeUI` to instantiate a `SampleDCDef` object. The `SampleDCDef` object, which is another class you have to implement, is described in Section 20.4, "Implement the Data Control Definition Class".

Example 20-6 shows the `invokeUI` method:

Example 20-6 invokeUI

       public boolean invokeUI()
       {
          // First check if this is a JDev environment.
          if (mJdevCtx != null && mSrc != null)
          {
             if (extractDataSourceInfo(mSrc))
             {
                SampleDCDef def = new SampleDCDef(mSrcLoc,mDCName);
                mDefinition = def;
                return true;
             }
             return false;
          }
          return false;
       }

## 20.3.6 Implementing the getDefinition Method

This method returns the definition of the data control that was created from information gathered from the dropped source node. The method has the following signature:

Example 20-7 getDefinition Signature

    public abstract AbstractDefinition getDefinition();

The `AbstractDefinition` class is the data control definition class that you created. See Section 20.4, "Implement the Data Control Definition Class".

In the simple CSV adapter, the `getDefinition` method returns the value of the `mDefinition` class variable, which was set in the `invokeUI` method. `mDefinition` refers to the data control definition class that you created (`SampleDCDef` in the case of the simple CSV adapter).

Example 20-8 getDefinition

       public AbstractDefinition getDefinition()
       {
          return mDefinition;
       }