Co-author, Paul Lacy

Introduction

In IBM App Connect Enterprise V11.0.0.5, the Integration API has been re-introduced so that you can administer your integration nodes, integration servers and their deployed resources using a Java Application.

The REST Administration API is used by the Integration API to send requests and handle responses that are sent back.

Here is an example REST request being made using curl to a local integration node and the JSON response that is sent back. The same REST request can be made using Java through the Integration API and model classes are provided which allow you to easily access specific fields in the response.

New Classes in Integration API

In ACE v11.0.05, these new Java packages and classes have been provided:

com.ibm.integration.admin.proxy
This package has new classes to use for administering an integration node, integration server and deployed resources.

com.ibm.integration.admin.model
This package has classes which are a model representation of an integration node, integration server and deployed resources. You can use get methods to access specific properties.

com.ibm.integration.admin.http
This package has classes which allow you to send direct requests and receive responses to/from a local or remote integration node or integration server.

com.ibm.integration.admin.logger
This package has classes which allow you to enable service trace to log requests and responses between your Java client and the integration nodes or integration servers.

Classes in the package com.ibm.broker.config.proxy are now deprecated. Limited capability is supported in V11. You should now look to migrating your Java code to use classes in com.ibm.integration.admin.proxy instead.

The classes connect to the node or server over HTTP and issue REST requests to the integration node or integration server and process the REST responses. If the node or server is local, then the connection is made to a Unix Domain Socket or a Named Pipe (on Windows).

Pre-requisite JAR files

In order to use the Integration API to send REST requests and process the JSON responses, some JAR files must be added to your CLASSPATH. If you have run the mqsiprofile, then they are automatically added.

Proxy Classes

The IntegrationNodeProxy and IntegrationServerProxy classes in com.ibm.integration.admin.proxy are the starting point for using the Integration API.

You can connect to a local or remote integration node using the IntegrationNodeProxy class. It has the following constructors:

  1. To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
  2. To use the class with a local integration node, you just need to supply the name of the integration node.
  3. To use the class with a remote integration node, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

You can connect to a local or remote integration server using the IntegrationServerProxy class. Note that, you cannot connect to a node-owned server. It has the following constructors:

  1. To use the class from within a JavaCompute node, you can call the constructor without passing any parameters.
  2. To use the class with a local integration server, you just need to supply the name of the integration server and the location of the work directory.
  3. To use the class with a remote integration server, you need to supply the hostname and REST Admin API port. If Admin Security is enabled, then you need to supply the userid, password and a boolean to indicate whether to send the requests using HTTP or using HTTPS.

These ACE resources can be administered using the Integration API classes:

There is a proxy class for each of the main resource types:

Model Classes

Each proxy class has a corresponding model class for processing the JSON response:

To process the JSON responses, the model classes in com.ibm.integration.admin.model, can be used to drill down into each response section to extract the piece of information that you are trying to access.


For example, the JSON response for the query on the integration node that was shown at the top of this article is modeled by these classes in the com.ibm.integration.admin.model.node package.


Model Caching

Each proxy class will cache the model after it has been obtained from the integration node or integration server. Each call to get the properties has a refresh option. If you need to refresh the model, set refresh to true otherwise it will return the existing model.

Example Code

Here is a simple code snippet which shows how to get a proxy for a node-owned server called ‘Server1’ and then lookup a specific application called ‘myApp’ so that it can be stopped and then started again:

IntegrationServerProxy Class

The IntegrationServerProxy class allows you to administer several resources. There are getter methods for several resources:

You can use three different methods for deploying a BAR file:

  • Specify the File object for the BAR file
  • Specify an InputStream and the name of the BAR file
  • Specify the path to the BAR file

In addition, you can stop, start and delete deployed resources:

You can also stop and start an integration node owned integration server, but you cannot start/stop an independent integration server, in this case an exception will be thrown.
ApplicationProxy, RestApiProxy, ServiceProxy and MessageFlowProxy all have start/stop methods.

Debugging

Service trace can help diagnose any issues with your classes or help the IBM Support team to debug the issue. When running as a stand alone Java application, tracing can be enabled using IntegrationAPI.class contained in package com.ibm.integration.admin.logger:

Below is a sample service trace of a call to getIntegrationServerByName:

HttpClient and HttpResponse

In addition to the proxy and model classes, there are two classes called HttpClient and HttpResponse which can be used to send a direct REST request and then process the REST response. These classes underpin the proxy classes. You may want to use these classes if there is no specific method that you want to use in the proxy classes.

The HttpClient class can be used with a local or remote integration node or integration server. When accessing a local integration node or integration server, a Unix Domain Socket or Named Pipe is used.

HttpClient

The HttpClient allows you to use the different REST verbs: GET, POST, PATCH and DELETE on ACE resources:

HttpResponse

The HttpResponse class can be used to access the REST response. It can be be used to get the last URL request that was used by the IntegrationNodeProxy or IntegrationServerProxy by using the getUrlPath()

The parseResponseBody() method is useful to get a model representation of the response body, for example:

IntegrationNodeModel intNodeObject = lastHttpResponse.parseResponseBody(IntegrationNodeModel.class);

Example Code using HttpClient and HttpResponse

The following code snippet shows how you can use the HttpClient and HttpResponse classes. It sends a REST request to a Node-owned integration server and uses the IntegrationServerModel class to parse the response. This is the equivalent to using the IntegrationServerProxy class and is shown for comparison. Obviously, it is easier to use the IntegrationServerProxy class as it does the bulk of the work for you!

You may want to use the HttpClient and HttpResponse classes to access deployed resources which do not have proxy classes or models, for example deployed Policies or a specific Message Flow Node in a Message Flow.

Deprecated Classes

Classes in the package com.ibm.broker.config.proxy are deprecated. Some classes like BrokerProxy and ExecutionGroupProxy can be used but not all. One way to ease your migration is to use BrokerProxy::getNewIntegrationNodeProxy() or ExecutionGroupProxy::getNewIntegrationServerProxy() methods. These methods return an IntegrationNodeProxy or IntegrationServerProxy representation of the integration node or integration server. It is recommended to migrate to using classes in com.ibm.integration.admin.* packages.

Summary

In this article, I have described how to use the new packages and classes in the Integration API provided in App Connect Enterprise v11.0.0.5.

The classes in com.ibm.integration.admin.proxy and com.ibm.integration.admin.model packages allow you to administer your integration node or integration server and their deployed resources. The HttpClient and HttpResponse classes underpin the proxy classes. They can be used directly if required.

The classes in com.ibm.broker.config.* are deprecated. It is strongly recommended for Java applications to be migrated to use the new classes in the com.ibm.integration.admin.* packages.

You can read further information about the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.doc/be43410_.htm

You can view the Javadoc for the Integration API in the Knowledge Center here: https://www.ibm.com/support/knowledgecenter/SSTTDS_11.0.0/com.ibm.etools.mft.cmp.doc/index.html?view=embed

8 comments on"Using the Integration API with ACE v11"

  1. So in this year, have any fixpack for modify UDF-Properties in runtime ? Because we need it in this year, for new project.

    • BenThompsonIBM August 20, 2019

      Hi DuaDua,
      Due to revenue recognition rules we’re unable to guarantee particular future features for specific dates … however we are very closely tracking the requirement (for delivery in a future v11 fix pack) for just such an action in the administrative REST API (and as per this article, also reflected in the Java integration API). It is likely that this POST action would be implemented to deliberately not persist flow UDP changes at server restart.
      Cheers,
      Ben

  2. i’m using ACE v11.0.0.5
    i wan’t to use some funtions: getUserDefinedPropertyNames()/getUserDefinedProperty()/setUserDefinedProperty()
    i see at https://www.ibm.com/support/knowledgecenter/en/SSMKHH_10.0.0/com.ibm.etools.mft.doc/ac00325_.htm
    and do the tutorial
    But the packge MessageFlowProxy don’t have that function.
    Is it right ?
    And how can I get/set the UDPs from IBM API.
    thanks alots

  3. I installed ACE 11.0.0.4. And I using this version.
    But I cant import package: com.ibm.integration.admin.proxy.*
    Maybe it not include this package.
    I just import pakage: com.ibm.broker.config.proxy.*
    I cant find the “admin” folder in install_dir\server\sample.
    Please, how can I import this packge ?

    • @hung,
      You need ACE v11.0.05.
      The new Java packages and classes were introduced with the Integration API in IBM App Connect Enterprise V11.0.0.5.
      Regards,
      Ian

  4. matthiasblomme August 01, 2019

    Are there any replacements for
    com.ibm.broker.config.proxy.BarEntry
    com.ibm.broker.config.proxy.BarFile
    com.ibm.broker.config.proxy.DeploymentDescriptor

    Or are they not being deprecated?

    • SanjayNagchowdhury August 05, 2019

      Hi Matthias,

      The classes and their methods are deprecated. What were you trying to do exactly with these classes?
      You can deploy a BAR file to an Integration Server using com.ibm.integration.admin.proxy.IntegrationServerProxy.deploy

      There is an example Java file which shows how to deploy in:

      /server/sample/admin/IntegrationAPI/DeployBAR.java

      Read Instructions.txt in the same directory. There are other examples in the same directory too.

      Thanks

      Sanjay

Join The Discussion

Your email address will not be published. Required fields are marked *