XCC Sessions

Save PDF

Last Updated: April 14, 2026
3 minute read

MarkLogic Server
Version 10.0
Documentation

XCC programs use the Session interface to set up and control communication with MarkLogic Server. XCC automatically creates and releases connections to MarkLogic Server as needed, and automatically pools the connections so that multiple requests are handled efficiently.

A Session handles authentication with MarkLogic Server and holds a dynamic state, but it is a lightweight object. It is OK to create and release Session objects as needed and as makes logical sense for your program. Do not expend effort to pool and reuse them, however, because they are not expensive to create. For example, if your program is doing multiple requests one after another, create a Session object at the beginning and close it when the last request is complete.

An instance of Session is created using an instance of ContentSource. An instance of ContentSource in turn is created using static methods from ContentSourceFactory. The method newContentSource() is overloaded to provide multiple options to instantiate ContentSource.

One option is to use the following method overload signature:

static ContentSource newContentSource(
  java.lang.String host,
  int port,
  java.lang.String username,
  char[] password
)

The following example uses that method overload signature:

String host = "devhost";
int port = 8050;
String username = "client-username";
String password = "secret";

ContentSource contentSource =
  ContentSourceFactory.newContentSource(
    host,
    port,
    username,
    password.toCharArray()
  );
  
Session session = contentSource.newSession();
...

Another option is to use a connection uri as an input using this method overload signature:

static ContentSource newContentSource(
  java.net.URI uri
)

The following example shows how to use that method overload signature to construct and pass a uri:

import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
...

String host = "devhost";
int port = 8050;
String username = "client-username";
String encodedUsername = URLEncoder.encode(username, StandardCharsets.UTF_8.toString());
String password = "secret";
String encodedPassword = URLEncoder.encode(password, StandardCharsets.UTF_8.toString());

URI uri = new URI(
  "xcc://" + encodedUsername + ":" + encodedPassword + "@" + host + ":" + port
);

ContentSource contentSource = ContentSourceFactory.newContentSource(uri);
Session session = contentSource.newSession();
...

URLEncoding user credentials ensures that special characters are properly encoded before being concatenated as part of the connection uri.

If the connection must be secured (for example, with the xccs protocol), then you must supply an instance of SecurityOptions using this method overload signature:

static ContentSource newContentSource(
  java.lang.String host,
  int port,
  java.lang.String user,
  char[] password,
  java.lang.String contentbaseName,
  SecurityOptions options
)

The following example uses that method overload signature:

String host = "devhost";
int port = 8050;
String username = "client-username";
String password = "secret";

SSLContext sslContext = SSLContext.getInstance("TLSv1.3");
// initialize as per your company security policy
sslContext.init(null, null, null);
SecurityOptions sslOptions = new SecurityOptions(sslContext);

ContentSource contentSource =
  ContentSourceFactory.newContentSource(
    host,
    port,
    username,
    password.toCharArray(),
    null,
    new SecurityOptions(sslOptions.getSslContext())
  );
  
Session session = contentSource.newSession();
...

Another option is to use this method overload signature to pass the uri and instance of SecurityOptions:

static ContentSource newContentSource(
  java.net.URI uri,
  SecurityOptions options
)

The following example uses that method overload signature:

import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
...

String host = "devhost";
int port = 8050;
String username = "client-username";
String encodedUsername = URLEncoder.encode(username, StandardCharsets.UTF_8.toString());
String password = "secret";
String encodedPassword = URLEncoder.encode(password, StandardCharsets.UTF_8.toString());

SSLContext sslContext = SSLContext.getInstance("TLSv1.3");
// initialize as per your company security policy
sslContext.init(null, null, null);
SecurityOptions sslOptions = new SecurityOptions(sslContext);

URI uri = new URI(
  "xccs://" + encodedUsername + ":" + encodedPassword + "@" + host + ":" + port
);

ContentSource contentSource = ContentSourceFactory.newContentSource(
  uri,
  new SecurityOptions(sslOptions.getSslContext())
);
Session session = contentSource.newSession();
...

See Coding Basics for other required class imports.

Develop with XCC

XCC Sessions

Table of Contents

XCC Sessions