Howto: Remote provisioning to a Talend Runtime. Managing TESB container.

Introduction

This page describes how we can manage remote Karaf container from Talend ESB using the JMX technology. We consider the code fragments of client application, which use MBean server connection by creating an MBean proxy. That proxy implement the access to the Karaf MBeans. It is local to the client, and emulates the remote Karaf MBean.

All work with features and bundles is done through:

  • FeatureServiceMBean proxy (similar to such command in shell: feature:addurl, feature:removeurl, feature:install, feature:uninstall);
  • FrameworkMBean proxy (osgi:start, osgi:stop);
  • JobControllerMBeanImpl proxy (job:list, job:start, job:stop);
  • RouteControllerMBeanImpl proxy (route:list, route:start, route:stop);
  • ServiceControllerMBeanImpl proxy (service:list, service:start, service:stop);

Requirements

Now we expect for all cases (routes, services, jobs, data services):

  • bundles are in Maven repo;
  • feature files are in Maven repo;

Data Services Deployment

Data Service consists of features file and bundles. Features file is in the Maven repository and describe one Karaf feature. This feature consists of service bundle and job bundles. Both service bundle and job bundles are in Maven repository.

  1. Connect to remote Karaf MBean server
  2. Create MBean proxies
  3. Add URL to the features file as described here
  4. Install feature by name as described here

Routes deployment

The feature might not be introduced If essentially one jar is necessary to deploy. In this case we need to do just the following steps:

  1. Connect to remote Karaf MBean server
  2. Create MBean proxies
  3. Install and start bundles using their URL's

Services deployment

In case services have features file in Maven repository, deployment is the same steps as for Data Service. If no, we can do it the same way as for Routes deployment.

Jobs deployment

Every job is just one jar necessary to deploy. So, in case of job deployment we need to do just similar steps as described in Routes deployment.

Connection to remote MBean server

To allow JMX client interact with Karaf JMX agent, we have to create an RMI connector client and configured it to connect to an RMI connector server. In following code fragment we created credentials for authentication to the Karaf MBean.

    HashMap<String, String[]> environment = new HashMap<String, String[]>();
    String username = "karaf";
    String password = "karaf";
    String[] credentials = new String[] { username, password };
    environment.put("jmx.remote.credentials", credentials);

As you can see, we should know Karaf username and password. In case of Talend ESB container we can see this credentials in configuration file \container\etc\users.properties

Than we going to create RMI connection using JMX service URL.

    JMXServiceURL url = new JMXServiceURL("service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-trun");
    JMXConnector jmxc = JMXConnectorFactory.connect(url, environment);

We can find this URL for Talend ESB container in configuration file \container\etc\org.apache.karaf.management.cfg

Next step, using RMI connector we can get connection to Karaf MBean server:

    MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();

After finish all managment actions we should close the connection:

    jmxc.close();

Creating MBean proxies to access an MBean through a Java interface

In order to get access to needed methods we should use FeaturesServiceMBean, FrameworkMBean, JobControllerMBeanImpl, RouteControllerMBeanImpl, ServiceControllerMBeanImpl. For these reasons we add appropriate dependencies into the project pom.xml:

		<dependency>
  			<groupId>org.apache.karaf.features</groupId>
  			<artifactId>org.apache.karaf.features.management</artifactId>
  			<version>2.2.2</version>
  		</dependency>
  		<dependency>
  			<groupId>org.apache.aries.jmx</groupId>
  			<artifactId>org.apache.aries.jmx</artifactId>
  			<version>0.3</version>
  		</dependency>
  		<dependency>
  			<groupId>org.talend.esb.job</groupId>
  			<artifactId>org.talend.esb.job.controller</artifactId>
  			<version>5.0-SNAPSHOT</version>
  		</dependency>

So import these classes first:

                import org.apache.karaf.features.management.FeaturesServiceMBean;
                import org.osgi.jmx.framework.FrameworkMBean;
                import org.talend.esb.job.controller.internal.management.JobControllerMBeanImpl;
                import org.talend.esb.job.controller.internal.management.RouteControllerMBeanImpl;
                import org.talend.esb.job.controller.internal.management.ServiceControllerMBeanImpl;

We should create featuresServiceMBeanProxy using org.apache.karaf.features.management.FeaturesServiceMBean to be able to add repositories, install and uninstall features:

                ObjectName mbeanName = new ObjectName("org.apache.karaf:type=features,name=trun");
		FeaturesServiceMBean featuresServiceMBeanProxy = 
                                      JMX.newMBeanProxy(mbsc, mbeanName, FeaturesServiceMBean.class, true);

We should create osgiFrameworkProxy using org.osgi.jmx.framework.FrameworkMBean class to be able to add start and stop bundles:

		ObjectName mbeanName = new ObjectName("osgi.core:type=framework,version=1.5");
		FrameworkMBean osgiFrameworkProxy = JMX.newMBeanProxy(mbsc, mbeanName,
				FrameworkMBean.class, false);

We should create jobControllerMBeanProxy using org.talend.esb.job.controller.internal.management.JobControllerMBeanImpl to be able to get list of jobs, start and stop job:

                ObjectName mbeanName = new ObjectName("org.talend.esb:type=controller,name=job");
		ControllerMBean jobControllerMBeanProxy = JMX.newMBeanProxy(
				mbsc, mbeanName, ControllerMBean.class, false);

We should create routeControllerMBeanProxy using org.talend.esb.job.controller.internal.management.RouteControllerMBeanImpl to be able to get list of routes, start and stop route:

                ObjectName mbeanName = new ObjectName("org.talend.esb:type=controller,name=route");
		ControllerMBean routeControllerMBeanProxy = JMX.newMBeanProxy(
				mbsc, mbeanName, ControllerMBean.class, false);

We should create serviceControllerMBeanProxy using org.talend.esb.job.controller.internal.management.ServiceControllerMBeanImpl to be able to get list of services, start and stop service:

                ObjectName mbeanName = new ObjectName("org.talend.esb:type=controller,name=service");
		ControllerMBean serviceControllerMBeanProxy = JMX.newMBeanProxy(
				mbsc, mbeanName, ControllerMBean.class, false);

Usecases of MBean proxies

Add/remove repository in remote Karaf container

We can add or remove repository URL in Karaf container using featureServiceMBeanProxy based on Karaf API:

    featureServiceMBeanProxy.addRepository("mvn:com.talend.if.examples/osgi/1.0/xml/features");
      //...
    featureServiceMBeanProxy.removeRepository("mvn:com.talend.if.examples/osgi/1.0/xml/features");
Install/uninstall Karaf features in remote container

We can install or uninstall features in Karaf container using featureServiceMBeanProxy based on Karaf API:

    featureServiceMBeanProxy.installFeature("tif-example-claimcheck");
      //...
    featureServiceMBeanProxy.uninstallFeature("tif-example-claimcheck");
Start/stop bundles in remote Karaf container

We can start and stop bundles in Karaf container using osgiFrameworkProxy based on standard JMX API:

    String bundleURL = "mvn:org.talend.esb.examples.rent-a-car/crmservice-common/4.2.1";
    long bundleNumber = osgiFrameworkProxy.installBundle(bundleURL); 
    osgiFrameworkProxy.startBundle(bundleNumber);
        //...
    osgiFrameworkProxy.stopBundle(bundleNumber);
Start/stop and get list of jobs in remote Karaf container

We can start and stop jobs in Karaf container using jobControllerMBeanProxy based on JobController JMX API:

    String jobName = "some_job_name";
    jobControllerMBeanProxy.start(jobName, arguments);
    jobControllerMBeanProxy.list();
      //..
    jobControllerMBeanProxy.stop(jobName);
Start/stop and get list of routes in remote Karaf container

We can start and stop jobs in Karaf container using routeControllerMBeanProxy based on JobController JMX API:

    String routeName = "some_route_name";
    routeControllerMBeanProxy.start(routeName, arguments);
    routeControllerMBeanProxy.list();
      //..
    routeControllerMBeanProxy.stop(routeName);
Start/stop and get list of services in remote Karaf container

We can start and stop services in Karaf container using serviceControllerMBeanProxy based on JobController JMX API:

    String serviceName = "some_service_name";
    serviceControllerMBeanProxy.start(serviceName, arguments);
    serviceControllerMBeanProxy.list();
      //..
    serviceControllerMBeanProxy.stop(serviceName);

Using Jconsole for management purposes

You can also use JConsole GUI to manage Karaf instance through JMX interface.

Provide Karaf URL and needed credentials (username/password) for JConsole.

You can find serviceURL in container/etc/org.apache.karaf.management.cfg file of you TESB container.

Username and password are in container/etc/users.properties file.

After this you'll see the following view:

As you can see we have three MBeans in org.talend.esb.controller category:

  • job;
  • route;
  • service.

For every MBean from list we can expose three types of operations:

  • start - starts job/route/service by name (set required name as first parameter). Additional arguments may be passed as the second parameter;
  • stop - stops job/route/service; by name (set required name as parameter for command call);
  • list - shows list of jobs/routes/services present in Karaf.

All these operations are the same operations that you can call from Karaf shell:

  • job:start,
  • service:list
  • etc.

or from you code:

serviceControllerMBeanProxy.list();
routeControllerMBeanProxy.stop(routeName);

etc.

Creating and registration of notification listener

Some MBeans send notifications, which we can receive and handle in our client application. For this purposes we need to create notification listener and register it in current MBeanServerConnection instance.

             public class ClientListener implements NotificationListener {
                 public void handleNotification(Notification notification,
                                   Object handback) {  
             }
             //...
             ClientListener clientListener = new ClientListener();
             //...
             mbsc.addNotificationListener(mbeanName, clientListener, null, null);

Management with artifacts deployed to the OSGI Bundle Repository (OBR)

Currently there is no known JMX API to work with OSGi Bundle Repository (OBR) in Karaf (RepositoryAdmin MBean is needed for this purposes). But there is a way to get bundles from OBR if we will follow next requirements:

For all cases (routes, services, data services) we expect:

  • bundles are in OBR;
  • feature files are in maven repo;
  • this feature file describes bundles in a way to use OBR
          <feature name="jbi" version="${version}" resolver="(obr)">
          <!-- ... -->
          <bundle>bundle:(symbolicname=bundle_name)</bundle>

not like as we described bundles earlier:

          <bundle>mvn:org.talend.esb...</bundle>)
  • also we expect that OBR feature is installed in Karaf:
          karaf@trun> features:install obr
  • URL for OBR with required bundles is already known by Karaf (use command: obr:addurl some_url);

External links

 
how-to-karaf-jmx-remote-management.txt · Last modified: 2011/12/17 03:51 (external edit)
 
 
Recent changes RSS feed Driven by DokuWiki