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.

The CoreMedia system supports gRPC and CORBA for internal communication. While servers always offer both protocols for clients to connect, clients can be configured to use either gRPC or CORBA. The protocol can be chosen freely on each start of a component. Currently, CORBA is the default protocol.

Note

With release 2512.0 of the CoreMedia system, the Workflow Server does not yet offer gRPC services to its clients. Activating gRPC on Unified API clients won't do any harm as long as these are of release 2512.0, too. Future clients, though, will fail to connect to that Workflow Server if gRPC is active on them.

Keep this in mind when operating a mixed-release CoreMedia system setup. In such scenarios (e.g., during upgrades), it is recommended to leave clients in their default protocol mode which is CORBA.

Passing Parameters Directly (CORBA only)

A classic way of opening a CORBA 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:40180/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 (CORBA and gRPC)

This is the recommended way of configuring and opening a connection. It covers both CORBA and gRPC connections and allows for specification of connection parameters through environment variables which is the preferred approach in Docker or Kubernetes environments.

You can pass a java.util.Map to the login method. The keys are typically chosen from a number of constants defined in the class Cap. The values in the map are normally strings. When working purely with environment variables, this map can be left empty but it must not be null.

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

In the previous example for CORBA, you can see that the initial workflow server URL is explicitly passed as a 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.

An example for connecting via gRPC looks like this:

Map<String,?> params = new HashMap<>();
params.put("spring.grpc.client.channels.cap.address", "localhost:40165");
params.put(Cap.HTTP_BASE_URI, URI.create("http://localhost:40180"));
params.put(Cap.USER, "admin");
params.put(Cap.DOMAIN, "");
params.put(Cap.PASSWORD, "admin");
params.put(Cap.USE_WORKFLOW, "false");
CapConnection connection = Cap.connect(params);

Here, no connection to the Workflow Server is included. For details on using the Workflow Server with gRPC connections, see below.

In the following, you will find summarized the available properties. All names prefixed with Cap. refer to constants in class com.coremedia.cap.Cap.

Note

To enable gRPC on a Unified API client, either environment variable REPOSITORY_USEGRPC=true must be specified or Java System Property repository.use-grpc=true be passed to the client application. This is to clearly separate modes of operation.

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. Example for CORBA:

Map<String, ?> params = new HashMap<>();
params.put(Cap.CONTENT_SERVER_URL, "http://localhost:40180/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 for CORBA Connection in Server 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:40180/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 (?). The constant values in class com.coremedia.cap.Cap define the possible parameter keys. Among those are, e.g.:

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.