Apiconnect-collective-jmx NPM

apiconnect-collective-jmx

Overview

The apiconnect-collective-jmx library provides helper functions for communicating with a WAS Liberty Collective, as well as JMX encoding tools to allow creation of custom JMX messages.

Usage

Install by running npm i --save apiconnect-collective-jmx.

Pre-defined Modules

This toolkit comes with a collection of modules and functions for performing operations against a collective.

Example

var jmx = require('apiconnect-collective-jmx');
var path = require('path');
var payload = jmx.collective.registerHost({
  rpcHost: 'someHost',
  rpcUser: 'someUser',
  sshPrivateKey: path.resolve('path', 'to', 'key_rsa');
});

For a full list, see the API Reference.

Make your own JMX requests

If there are no helper libraries defined for the JMX calls you'd like to make, then you have the option of defining your own using the same common modules used throughout this toolkit.

Simple Example

Using the Encoder, Payload and Endpoint objects, you can construct a JMX payload with the Encoder, target the REST resource with the Payload and then send the request to a specific server with Endpoint!

var jmx = require('apiconnect-collective-jmx');
var Encoder = jmx.Encoder;
var Payload = jmx.Payload;
var Endpoint = jmx.Endpoint;
var url = require('url');

// Make an encoder instance.
var encoder = new Encoder();

// Add parameters in order!
// Pretend we're calling an endpoint that takes a title (string), a size (int)
// and whether or not it's available (boolean).
encoder.addString('foo');
encoder.addNumber(2);
encoder.addBoolean(true);
// Send a JMX payload to {host:port}/targetResource!
var payload = new Payload('/targetResource', 'POST', encoder.encodeJson());

// Can also take a 3rd options param!
var controller = new Endpoint('localhost', '9443');

// Give it the payload, options and a callback!
controller.request(payload, {}, function(err, response) {
  if (err) console.error('oh noes!');
  else {
    console.log('Made a new widget!');
    console.log(response);
  }
});

Advanced Usage

Types

Here are the Java types available on the Encoder's types object:

JavaObject (java.lang.Object)
String (java.lang.String)
Integer (java.lang.Integer)
Double (java.lang.Double)
Boolean (java.lang.Boolean)
HashMap (java.util.HashMap)
ArrayList (java.util.ArrayList)

Using these static type definitions will simplify your usage, and help avoid typos within Java types on your payloads. See the examples below for usage of the Encoder.types collection.

Add an Array

var names = ['foo', 'bar' ];
var encoder = new Encoder();
encoder.addArray(names, encoder.types.String);

Add a Map

var map = {
  'foo': 2,
  'bar': 3,
};
var encoder = new Encoder();
encoder.addMap(map, encoder.types.String, encoder.types.Integer);

Add a Custom Value

Using the encoder doesn't limit you to the predefined types! In fact, you can create your own custom entries with the addSimpleValue function.

If you know the expected Java type at the target API level, you can specify it as a string!

var widgetInstance = getMagicWidget();
var encoder = new Encoder();

encoder.addSimpleValue(widgetInstance, 'com.foobar.Widget', 'java.lang.Object');

API Reference

Modules

Classes

apiconnect-collective-jmx

Collective

Kind: global class

Collective

new Collective()

Operations for registering and unregistering host machines, as well as joining and removing applications from a collective.

Collective.COLLECTIVE_REGISTRATION_MBEAN

The path string for collective registration operations on a Liberty JMX collective controller.

Kind: static property of Collective

Collective.Join(options)

Generates the JMX command to join a member server to a collective.

Kind: static method of Collective

Param	Type	Description
options	object	The options object.
options.hostName	string	The hostname of the member.
options.wlpUserDir	string	The path on the host to the 'usr' folder that contains the member.
options.serverName	string	The name of the member to join to the collective.
options.wlpInstallDir	string	The directory of the wlp installation.
options.keystorePassword	string	The password for the certificates generated as a part of the collective join operation.
options.certProperties	object	An options object for changing the behaviours of certificate generation.
options.hostAuthInfo	object	An options object for defining properties used by the collective to remotely access the host machine of the member.
options.rpcHost	string	The Host address of the remote server
options.rpcUser	string	The username of an account
options.rpcUserHome	string	The UserHome directory of rpcUser that can run RPC commands against the host. Does not apply if SSH is used.
options.rpcPort	string	The RPC port of the member host. Does not apply if SSH is used.
options.rpcUserPassword	string	The password for the user account running RPC commands. Does not apply if SSH is used.
options.hostAuthInfo.sudoUser	string	On systems where "sudo" is available, this will be the username of a sudoer for elevating SSH commands. Only applies to SSH.
options.sudoPassword	string	The password for the sudoer. Only applies to SSH.
options.sshPublicKeyPath	string	The path to the SSH public key.
options.sshPrivateKeyPath	string	The path to the SSH private key.
options.sshPrivateKeyPassword	string	The password for the SSH private key.
options.useHostCredentials	boolean	Tells the member to inherit its credentials configuration from the host's configuration (requires the host to already have been registered with the collective).
options.hostReadList	Array	The list of locations on the host with allowed read access.
options.hostWriteList	Array	The list of locations on the host with allowed write access.

Collective.Remove(options)

Generates the JMX command to remove a member server from a collective.

Kind: static method of Collective

Param	Type	Description
options	object	The options object.
options.hostName	string	The hostname of the member.
options.wlpUserDir	string	The path on the host to the 'usr' folder that contains the member.
options.serverName	string	The name of the member to join to the collective.

Collective.registerHost(options)

Generates the JMX command to register a host in a collective.

Kind: static method of Collective

Param	Type	Description
options	object	The options object.
options.hostName	string	The hostname of the member.
options.rpcHost	string	The Host address of the remote server
options.rpcUser	string	The username of an account
options.rpcUserHome	string	The UserHome directory of rpcUser that can run RPC commands against the host. Does not apply if SSH is used.
options.rpcPort	string	The RPC port of the member host. Does not apply if SSH is used.
options.rpcUserPassword	string	The password for the user account running RPC commands. Does not apply if SSH is used. * @param {string=} options.sshPrivateKeyPath - The path to the SSH private key.
options.sshPrivateKeyPassword	string	The password for the SSH private key.

Collective.unregisterHost(options)

Generates the JMX command to unregister a host.

Kind: static method of Collective

Param	Type	Description
options	object	The options object.
options.hostName	string	The hostname of the member.

Collective.updateHost(options)

Generates the JMX command to update a host info.

Kind: static method of Collective

Param	Type	Description
options	object	The options object.
options.hostName	string	The hostname of the member.
options.rpcHost	string	The Host address of the remote server
options.rpcUser	string	The username of an account
options.rpcUserHome	string	The UserHome directory of rpcUser that can run RPC commands against the host. Does not apply if SSH is used.
options.rpcPort	string	The RPC port of the member host. Does not apply if SSH is used.
options.rpcUserPassword	string	The password for the user account running RPC commands. Does not apply if SSH is used. * @param {string=} options.sshPrivateKeyPath - The path to the SSH private key.
options.sshPrivateKeyPassword	string	The password for the SSH private key.

Encoder

Kind: global class

Encoder
- instance
- static
  - .types