I have attached a zip file containing the new u4etx.jar file, a sample program, and some documentation. Use at your own risk. No warranties expressed or implied. Software AG will make the jar file available as part of the Technical Paper in the future.
Here’s a copy of the Technical Paper from ServLine24:
Command and Information Services using Java
The Broker Command and Information Services (CIS) is used by both Broker Control Center (BCC) and the System Management Hub (SMH) for monitoring and controlling Broker. It’s also possible to call these services directly, so anything that can be done through BCC or SMH can also be done by direct calls from a program.
The principal difficulty with calling CIS from Java is that the services use data structures of some complexity. These data structures and supporting methods and classes for calling CIS from Java are now available in an unsupported package, contained in u4etx.jar file. Source code is supplied so that modifications can easily be done if needed. The supplied javadoc has the details of the classes and methods provided. The package can be downloaded here (select “extract all files”, then select a personal folder where the files can be extracted to).
Here is a simple program using the package to shut down all servers running under userid JavaServer. It’s also included as ServShut.java in the download above.
There are a couple of tricks related to CIS programming that bear mentioning.
For a server shutdown, CIS needs the internal ID assigned by Broker to the server, in order to do the shutdown. This is because there may be multiple servers with the same server name or user id, so there is no unique identifier other than the internal ID to shut down a specific server. The sample program scans for a specific user id and shuts down all internal IDs associated with that user id. The program could easily be modified to scan for a server name instead.
There is also a pitfall for the unwary in the package code. The Information call within CIS can potentially return a number of messages, rather than a single one. This is because the list of objects to be returned is a list of variable length. As many of the objects as can be returned within the Broker receive buffer (implemented as BlockLength in this package) will be returned in the first message. The package code makes no provision for doing more than one receive, in the case that the returned list will not fit into the receive buffer. So, potentially, there may be more servers active than are returned by the IServiceResponse. The BlockLength of 7200 in the sample program is large enough for the data from 20 servers to be returned. If there will be more than 20 servers running, the BlockLength will have to be increased. If the number of servers is known to be relatively constant, the BlockLength can be set to a size sufficient for the known maximum number of servers, and the package code used as is.
The sample program as supplied does not use the package methods to make the call for information on the servers. Instead explicit Broker calls are coded, to ensure that all messages returned as a result of the call are read and processed. This handles the more general cases, where the number of servers or other objects to be returned is not known.
Please note that neither this program nor the u4etx.jar package is officially supported by Software AG. The risk is that should the CIS structures or the EXX Java ACI change, the code in the u4etx.jar will have to be updated. However both have been stable and backwardly compatible for the last 3 releases over six years, so it is reasonable to expect this risk to be small. With the v711 release, a new release of CIS, version 3, includes some new data items in the Broker object. The u4etx.jar code does not include these data items, but they do not affect the functioning of the code.
Here’s the sample program code.
/**
** A simple program to shut down all servers that are running under the user id specified in the
** configuration section. It illustrates the basic principles of using the Command and Information
** Services from Java with the package contained in u4etx.jar. This jar file must be on the
** classpath at compile and at run time, as well as the usual entirex.jar or entxrt.jar files.
**
** 11/06/2003 sakdo
**/
import de.sagd.u4etx.cis.*;
import de.sagd.u4etx.cis.objects.*;
import de.sagd.u4etx.cis.params.*;
import de.sagd.u4etx.cis.utils.*;
import com.softwareag.entirex.aci.*;
public class ServShut {
static Broker broker;
static IServiceResponse res;
static CmdServiceMessage cmd;
static InfoServiceMessage info;
static String BrokerCallE;
static String CIServer = "SAG/ETBCIS/INFO";
// ----------------------------------------------------------------------
// configuration section for Broker
// BrokID = host and port where the target Broker is listening
// BUserID = user id that will issue the Information and Command requests
// ServerUID = user id under which the server to be terminated is running
// ----------------------------------------------------------------------
static String BrokId = "localhost:1971";
static String BUserID = "sakdoIS";
static String ServerUID = "JavaServer";
// ----------------------------------------------------------------------
public static void main(String[] argv) {
try {
// Create a broker object
BrokerCallE="Logon";
broker = new Broker(BrokId,BUserID);
broker.logon();
// Create an InfoServiceMessage object to get information on active servers
info = new InfoServiceMessage();
info.setInterfaceVersion(InterfaceVersion.VERSION_2);
info.setBlockLength(new BlockLength(7200));
info.setObjectType(ObjectType.SERVER);
UserID suid = new UserID(ServerUID);
info.setUserID(suid);
// create a Command message object for the server shutdown
cmd = new CmdServiceMessage();
cmd.setInterfaceVersion(InterfaceVersion.VERSION_2);
cmd.setObjectType(ObjectType.SERVER);
cmd.setCommand(Command.SHUTDOWN);
cmd.setOption(Option.IMMED);
// create and send the request for info on active servers
// the following 2 lines of code (commented out) use methods from the package.
// However the response from Broker may consist of more than one message,
// which situation the package code did not handle.
// Here the lines are replaced with explicit calls to Broker to get all
// messages returned from the Information Service.
//
// ServiceRequest req = new ServiceRequest(broker, info);
// IServiceResponse res = req.sendReceive();
// create BrokerService object and make Conversation call to Broker
BrokerService oBService = new BrokerService(broker, CIServer);
Conversation oConv = new Conversation(oBService);
BrokerCallE="Send info request";
BrokerMessage bmResponse = oConv.sendReceive(new BrokerMessage(info.getMessage()));
res = new InfoServiceResponse(bmResponse.getMessage(), info.getObjectType());
ServTerm();
BrokerCallE="Receive server info";
// keep reading responses until a null object is returned from the receive request
//
while ( ( bmResponse = oConv.receive() ) != null ) {
res = new InfoServiceResponse(bmResponse.getMessage(), info.getObjectType());
ServTerm();
}
}
catch (BrokerException bE) {
System.out.println("Error at " + BrokerCallE + ": " + bE);
}
catch (ServiceResponseException sE) {
System.out.println("ServiceResponse error from package: " + sE);
}
catch (ServiceMessageException mE) {
System.out.println("ServiceMessage error at info.getMessage: " + mE);
}
}
private static void ServTerm()
throws de.sagd.u4etx.cis.ServiceResponseException {
// run through list of active servers
for (int i = 0; i < res.getCommonHeader().getCurrentNumObjects(); i++) {
// printout if needed
// System.out.println("SERVER [" + i + "] : " + res.getServiceResponseObject(i));
// Get the userid associated with the server and see if it's the one we want
IServiceResponseObject resO = res.getServiceResponseObject(i);
if ( resO.getUserID().equals(ServerUID) ) {
// shutdown requires the internal userid of the server
PUserID ServerPUID = new PUserID(resO.getPUserID());
cmd.setPUserID(ServerPUID);
// and send the shutdown command
ServiceRequest sendcmd = new ServiceRequest(broker, cmd);
IServiceResponse rescmd = sendcmd.sendReceive();
//the command itself returns only an error code which will be
//thrown as a ServiceResponseException if non-zero
}
}
}
}
Wayne Campos