Optional Arguments

This page describes each optional argument class and function in detail. To navigate between sections, use the table of contents on the right.

OptionalArg class

The OptionalArg class is the interface class for optional arguments. You use OptionalArg to set OnError and Attachment operations. OnError has continue or abort error options and Attachment has a flag to set read attachment summaries value.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
//if error occurs then abort the operation
List<Document> responseDocs =
        client.readDocuments(query, optItemNames,
        OptionalArg.OnError.ON_ERROR_ABORT_REMAINING).get();
//if error occurs then continue operation
List<Document> responseDocs =
        client.readDocuments(query, optItemNames,
        OptionalArg.OnError.ON_ERROR_CONTINUE).get();
//set the read attachment summaries flag
List<Document> responseDocs =
        client.readDocuments(query, optItemNames,
        OptionalArg.Attachment.READ_ATTACHMENT_SUMMARIES).get();

ComputeOptions

ComputeOptions is an extension of OptionalArg. See Compute with form

computeOptions {Object}

computeWithForm {boolean} -- when true, validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form. The default is false.

ignoreComputeErrors {boolean} -- when true, continues processing a document with a compute error. This option has no effect unless computeWithForm is also true. The default is false, stop processing a document with a compute error.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);

List<Item<?>> itemList = new ArrayList<Item<?>>();
    itemList.add(new TextItem("Form","Contact"));
    itemList.add(new TextItem("FirstName","Aaron"));
    itemList.add(new TextItem("LastName","Aardman"));
    itemList.add(new TextItem("City","Arlington"));
    itemList.add(new TextItem("State","MA"));

//the first argument to ComputeOptions is computeWithForm and the second
//is ignoreComputeErrors.
Document response = client.createDocument(new Document(itemList), new ComputeOptions(true, true)).get();

OnErrorOptions

Optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING". See OptionalArg

OptionalAccessToken

Registered application must acquire an access token from IAM service when executing a Proton request as a different user during client certificate authentication.

options {Object}

accessToken {String} -- An optional access token. See Act-as-User for details.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
List<Item<?>> itemList = new ArrayList<Item<?>>();
    itemList.add(new TextItem("Form","Contact"));
    itemList.add(new TextItem("FirstName","Aaron"));
    itemList.add(new TextItem("LastName","Aardman"));
    itemList.add(new TextItem("City","Arlington"));
    itemList.add(new TextItem("State","MA"));
List<Document> documentList = new ArrayList<Document>();
documentList.add(itemList);
//AccessToken can be provided to createDocuments as below.
List<Document> responseDocs =
        client.createDocuments(documentList,
        new OptionalAccessToken("ENBZePi34eK3rBwQsYD2iufa6JqxLm6JLp3UaZMK59g")).get();

OptionalChunkSizeKb

An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

options {Object}

chunkSizeKb {number} -- user-specified chunk size. i.e. 4 ( will be converted to 4kb )

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
//Optional chunk size in kb
ReadRichTextMgr readMgr =
        client.getReadRichTextMgr(query, Sets.newHashSet("Body", "text1", "text2"),
         new OptionalChunkSizeKb(4));

OptionalCount

An optional count of the maximum number of documents to read.

options {Object}

count {number} -- Integer value for the maximum number of documents to read.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
//Integer value for the maximum number of documents to read
List<Document> responseDocs =
        client.readDocuments("Form='Contact' and FirstName = 'fname'",
        new OptionalCount(10)).get();

OptionalFileNames

An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.

options {Object}

fileNames {Set <String>} -- Set of file names.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
//Set of file names as an optional argument
//First argument takes set of UNID and second takes set of file names
ReadAttachmentMgr readAttachmentMgr = client.getReadAttachmentMgrByUnid(
        Sets.newHashSet("73465A434EDD051A8825850B001B0EB2"),
        new OptionalFileNames(Sets.newHashSet("file1", "file2"));

OptionalItemNames

An optional array of item names. Use OptionalItemNames to read the given item names inside array. The default is to read no document items.

options {Object}

itemNames {List <String>} -- List of item names.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);

List<String> itemNames = new ArrayList<String>();
itemNames.add("FirstName");
itemNames.add("LastName");

String query = "Form='Contact' and FirstName = 'fname'";

//List of Item names
List<Document> responseDocs =
        client.readDocuments(query, new OptionalItemNames(itemNames)).get();

OptionalQueryArgs

An optional array of values to substitute in the query string. It accepts list/map of generic value and build query arguments for given name or ordinal values.

options {Object}

queryArgs {List <String/Double/ZonedDateTime>} -- query arguments see Domino Query Langauge.

Example (List)

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
List<T> queryArgList = new ArrayList<>();
    queryArgList.add((T)"fname");
    queryArgList.add((T) new Double(10));
    queryArgList.add((T) ZonedDateTime.now());

String query = "Form='Contact' and FirstName = ? and Experience = ? and Date = ?";

//List of Item names
List<Document> responseDocs =
        client.readDocuments(query, new OptionalQueryArgs<T>(queryArgList)).get();

Example (Map)

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);

String query = "Form='Contact' and FirstName = ?fn and Experience = ?ex and Date = ?dt";

Map<String, T> queryArgValue = new HashMap<String, T>();
    queryArgValue.put("fn", (T) "fname");
    queryArgValue.put("ex", (T) new Double(10));
    queryArgValue.put("dt", (T) ZonedDateTime.now());



//List of Item names
List<Document> responseDocs =
        client.readDocuments(query, new OptionalQueryArgs<T>(queryArgValue)).get();

OptionalQueryLimit

An optional set of limits on the query.

options {Object}

queryLimits {Object} An optional set of limits on the query.

maxViewEntriesScanned {number} The maximum number of view entries to scan.

maxDocumentsScanned {number} The maximum number of documents to scan.

maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
List<T> queryArgList = new ArrayList<>();
    queryArgList.add((T)"fname");
    queryArgList.add((T) new Double(10));
    queryArgList.add((T) ZonedDateTime.now());

String query = "Form='Contact' and FirstName = ? and Experience = ? and Date = ?";

//List of Item names
List<Document> responseDocs =
        client.readDocuments(query, new OptionalQueryArgs<T>(queryArgList),
        new OptionalQueryLimit(1000,10000, 400)).get();

OptionalStart

An optional zero-based start index. Use OptionalStart to page through a large set of matching documents.

options {Object}

start {number} An optional zero-based start index to page through a large set of matching documents.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
List<T> queryArgList = new ArrayList<>();
    queryArgList.add((T)"fname");
    queryArgList.add((T) new Double(10));
    queryArgList.add((T) ZonedDateTime.now());

String query = "Form='Contact' and FirstName = ? and Experience = ? and Date = ?";

//List of Item names
List<Document> responseDocs =
        client.readDocuments(query, new OptionalQueryArgs<T>(queryArgList),
        new OptionalQueryLimit(1000,10000, 400), new OptionalStart(2)).get();

ReadAttachmentSummaries

An optional boolean value specifying whether to read attachment summaries as described in @attachments.

options {Object}

readAttachmentSummaries {boolean} An optional boolean value specifying whether to read attachment summaries.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);

//set the read attachment summaries flag
List<Document> responseDocs =
        client.readDocuments(query, optItemNames,
          OptionalArg.Attachment.READ_ATTACHMENT_SUMMARIES).get();

OptionalSelection

Provides options that can be specified when calling Agent.run(). See admin section for additional information about Proton agent support.

There are two options that the caller may specify when calling Agent.run().

A document context which provides access to data between the caller and the agent. The caller may write data to a document. The agent can read that data when it runs and then in return may write additional data to the document which the caller may read. This is called the document context and it's an optional parameter that the caller provides in the run options. The document is identified by it's unid. The agent code has access to this document via the AgentContext.

A document selection which provides a selection of documents to the agent as a target for the run. The agent code has access to the document selection as UnprocessedDocuments. There are two ways to specify a document selection.

The caller provides a list of unids.
The caller provides a query. The server executes the query before running the agent. The found set is then passed to the agent.

Parameters

options {Object} -- optional run parameters for invoking the agent.

selection {Object} optional document selection criteria. Determines the list of selected documents that will be provided to the Agent as UnprocessedDocuments

search {Object} optional search parameters to be used for selecting documents - query {string} REQUIRED - A query string. - queryArgs {Array<Object>} An optional array of values to substitute in the query string. See Query arguments for details. - queryLimits {Object} An optional set of limits on the query. - maxViewEntriesScanned {number} The maximum number of view entries to scan. - maxDocumentsScanned {number} The maximum number of documents to scan. - maxMilliSeconds {number} The maximum number of milliseconds to spend executing the query.

unids {Array<string>} optional array of UNIDs.

context {Object} optional document that is provided to the Agent as AgentContext.

unid {string} The UNID of the agent context document.

You can provide either options.selection.search or options.selection.unids, but not both.

Example

Server server = new Server('your.server.com', 3002,
        new File("ca.crt"),
        new File("user.crt"),
        new File("user.key"),
        "Key@1234",     // key file passphrase
        "ID@1234",      // ID file password
        EXECUTOR_SERVICE);
Database client = server.useDatabase(TARGET_DATABASE);
Agent agent = client.useAgent("agent-with-selection-java");
List<Item<?>> itemList = new ArrayList<Item<?>>();
    itemList.add(new TextItem("Form", "Contact"));
    itemList.add(new TextItem("FirstName", "fname"));
    itemList.add(new TextItem("LastName", "lname"));
    itemList.add(new TextItem("State", "MH"));

Document document = new Document(itemList);
ListenableFuture<Document> response = client.createDocument(document);

Map<String, Object> queryArgument = new HashMap<String, Object>();
    queryArgument.put("ln", (Object) "lname");

    OptionalQueryArgs<Object> queryArguments = new OptionalQueryArgs<Object>(queryArgument);

    OptionalQueryLimit queryLimit = new OptionalQueryLimit(1000, 10000, 1000);
    OptionalSelection selection = new OptionalSelection("Form = 'Contact' and LastName = ?ln",
                                     queryArguments, queryLimit);
    OptionalContext context = new OptionalContext(response.get().getUnid());
    ListenableFuture<AgentRunResponse> response = agent.run(selection, context);

OptionalContext

See OptionalSelection for details.

Domino AppDev Pack

1.0.13

Node.js

Java

OptionalArg class

Example

ComputeOptions

Example

OnErrorOptions

OptionalAccessToken

Example

OptionalChunkSizeKb

Example

OptionalCount

Example

OptionalFileNames

Example

OptionalItemNames

Example

OptionalQueryArgs

Example (List)

Example (Map)

OptionalQueryLimit

Example

OptionalStart

Example

ReadAttachmentSummaries

Example

OptionalSelection

Parameters

Example

OptionalContext