CoreMedia Unified API Developer Manual, Version 7.5.45-10
4.1. Connection | 4.1.1. Creating a Connection

Before working with the Unified API, a connection to the server must be opened. The connection object implements the interface com.coremedia.cap.common.CapConnection. There are a number of static methods in the class com.coremedia.cap.Cap that allow you to specify various sets of parameters for logging on to Content Server and Workflow Server.

Passing Parameters Directly

The most common way of opening a connection is provided by a method of the class com.coremedia.cap.Cap with four parameters:

All parameters are passed as string values. The IOR URL is explained in more detail in the Operations Basics Manual. It is a means for bootstrapping the CORBA protocol.

String url = "http://localhost:44441/coremedia/ior";
CapConnection connection = Cap.connect(url,
  "user", "domain", "secret");

The login call will fail with an exception if the Content Server is not reachable. A connection to the Workflow Server is also opened, if the Workflow Server is reachable, but its absence does not abort the login sequence.

Because the IOR URL is cumbersome to write, the Unified API uses some rules for determining this parameter when it is omitted.

CapConnection connection = Cap.connect(null,
  "user", "domain", "secret");

If the system property coremedia.content.server.url is set, its value is used as the URL. Else, if the system property coremedia.configpath is set, the system tries to determine the URL from the file capclient.properties. Because the latter property is automatically set by the cm start script, there is no need to configure the URL when the Unified API client is started by means of a .jpif file.

When you use the built-in user repository of CoreMedia CMS and not an LDAP server for managing your users, you can set the domain parameter to null or omit it entirely.

CapConnection connection = Cap.connect(url, "user", "secret");

Passing Parameters as a Map

When you want to pass more parameters than available to the standard login methods or when you want to determine the parameters in a more flexible way, you can pass a java.util.Map to the login method. The keys must be chosen from a number of constants defined in the class Cap. The values in the map are normally strings.

Map<String,?> params = new HashMap<String,?>();
params.put(Cap.CONTENT_SERVER_URL,
  "http://localhost:44441/coremedia/ior");
params.put(Cap.WORKFLOW_SERVER_URL,
  "http://localhost:44450/workflow/ior");
params.put(Cap.USER, "admin");
params.put(Cap.DOMAIN, "");
params.put(Cap.PASSWORD, "admin");
CapConnection connection = Cap.connect(params);

In the previous example, you can see that the initial workflow server URL is passed as one parameter. Normally this is not required, because the Content Server acts as a naming service and provides the necessary information for connecting to other servers. However, in complex setups with multiple firewalls and connection redirection, it may be necessary that different clients connect via different URLs.

In the following, you will find summarized the available properties.

You can also create a connection without opening it immediately. Here you may pass a number of parameters by means of a map, but you can set additional parameters later before opening the connection.

Map params = Collections.singletonMap(Cap.CONTENT_SERVER_URL,
 "http://localhost:44441/coremedia/ior");
CapConnection connection = Cap.prepare(params);
connection.setUser("admin");
connection.setPassword("admin");
connection.open();

The methods that are available for setting the parameters of a connection are

Passing Parameters as a URL

While flexible, the creation of a map takes some lines of code, so that CoreMedia provides a simple method that works in many cases. The additional parameters beside the Content Server URL are inlined as URL parameters in that URL. This permits the compact configuration via a single string.

String url = "http://localhost:44441/coremedia/ior"+
  "?user=admin&password=admin&useworkflow=false";
CapConnection connection = Cap.connect(url);

Here the workflow component has been disabled entirely by the means of useworkflow=false. This reduces the resource requirements when the workflow connection is not needed at all.

Individual parameters are separated by ampersands (&), the entire set of parameters is separated from the IOR URL by a question mark (?). Possible parameters are:

Note that the well-known parameters are removed from the URL before it is resolved over the network. In particular, the password is not transmitted in clear text.