Extending Adapters

Adapters are created to communicate with external systems through a standard interface. Each adapter:

• uses the custom connection class to connect to the external system
• provides support for reconnection to the external system
• provides all necessary methods required for retrieving, adding, updating, and deleting data.

All adapters extend com.ifountain.core.datasource.BaseAdapter and implement the following method:

    Map<String, Object> getObject(Map<String, String> ids, List<String> fieldsToBeRetrieved)

Actions appropriate for the given adapter are defined as classes implementing the com.ifountain.core.datasource.Action interface and should implement the following method:

    execute(IConnection conn)

Therefore, the steps to create a new adapter are:

• write as many custom actions as needed as separate Groovy classes, each implementing the Action interface,
• write your adapter class, extending from BaseAdapter,
• put all necessary methods in your adapter, each method using one of the action classes you have implemented.

Sample Adapter Implementation

Let's review the DatabaseAdapter bundled with the product to see how the adapter framework is used to create a new adapter.

Implement Action(s)

Locate the following files in the RS_HOME\RapidSuite\grails-app\ext\datasource folder:

• ExecuteQueryAction.groovy
• ExecuteUpdateAction.groovy

Here is the implementation of the execute method in ExecuteQueryAction:

public void execute(IConnection conn) throws Exception {
        if(queryParams == null) {
            throw new Exception("QueryParameters cannot be null.");
        }
        logger.debug("Preparing statement.");
        PreparedStatement stmt = conn.getConnection().prepareStatement(sql);
        DatabaseConnectionImpl.setStatementParameters(queryParams, stmt);
        if(fetchSize > 0)
            stmt.setFetchSize(fetchSize);
        logger.debug("Executing query.");
        resultSet = stmt.executeQuery();
    }

Notice how JDBC connection object is retrieved from conn (of type IConnection/BaseConnection) and sets the resultSet by executing the query on the prepared statement.

The ExecuteQuertAction also defines an additional method getResultSet() to let the adapter access the search results:

public ResultSet getResultSet() {
        return resultSet;
    }

As expected, ExecuteUpdateAction implements the execute method differently and defines another additional method which applies to database updates:

public int getAffectedRowCount() {
        return affectedRowCount;
    }

Please review both files in detail. The 2 important points here are:

• implement the execute method as required by your external system.
• implement any additional methods that will be used by your adapter. For example, our DatabaseAdapter needed the getResultSet method from ExecuteQueryAction, and getAffectedRowCount method from ExecuteUpdateAction.

Implement the Adapter

Now lets look at how DatabaseAdapter utilizes these actions. Locate the following file in the RS_HOME\RapidSuite\grails-app\ext\datasource folder:

• DatabaseAdapter.groovy

The methods that are of interest here are  the executeQuery and executeUpdate methods. As an example, let's look at one implementation of executeUpdate:

public int executeUpdate(sql, queryParams) throws Exception{
        ExecuteUpdateAction action = new ExecuteUpdateAction(logger, sql, (Object[]) queryParams);
        executeAction(action);
        return action.getAffectedRowCount();
    }

Notice how an instance of ExecuteUpdateAction is passed into the executeAction which is inherited from the BaseAdapter. It will be executeAction's responsibility to call the execute method of the ExecuteUpdateAction.

Notice also, how the additional method getAffectedRowCount() is used to return the value from the adapter method.

Important point to keep in mind while implementing the adapter are:

• always extend BaseAdapter
• implement as many methods as needed to interface with the external system, using the action classes.

Implementing adapters according to the framework with the delegated Action classes enable RapidCMDB and products built on RapidCMDB to provide reconnection services to your adapter.