Domino AppDev Pack

1.0.14

com.hcl.domino.db Reference

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

Database class

createDocument

Creates a document.

Parameters

options {Object}

  • document {Object} REQUIRED - The new document contents. See domino-db document schema for information about representing a document as a JavaScript object.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • computeOptions {Object} An optional object specifying how to compute items on the new document. See Compute with form for details.
  • duplicateItems {boolean} An optional boolean value used to create duplicate items in the new document. See Duplicate items for details.

Return Value

{ListenableFuture<Document>} A promise resolved with new document

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"));

Document response = client.createDocument(new Document(itemList)).get();

createDocuments

Creates multiple documents. To create a single document, see Database::createDocument.

Parameters

options {Object}

  • documents {Array<Object>} REQUIRED - An array of new documents
  • accessToken {string} An optional access token. See Act-as-User for details.
  • computeOptions {Object} An optional object specifying how to compute items on the new documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
  • duplicateItems {boolean} An optional boolean value used to create duplicate items in the new documents. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Document> documentList = new ArrayList<Document>();

List<Item<?>> itemList1 = 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<Item<?>> itemList2 = new ArrayList<Item<?>>();
    itemList.add(new TextItem("Form","Contact"));
    itemList.add(new TextItem("FirstName","Brian"));
    itemList.add(new TextItem("LastName","Aardman"));
    itemList.add(new TextItem("City","Andover"));
    itemList.add(new TextItem("State","MA"));

documentList.add(itemList1);
documentList.add(itemList2);

List<Document> response = client.createDocument(documentList).get();

getWriteAttachmentMgr

Creates a manager for writing one or more attachments

Parameters

options {Object}

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

Return Value

{WriteAttachmentMgr} A object of a writable attachment manager. See Writing attachments for details on writing to the manager.

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);
WriteAttachmentMgr write = client.getWriteAttachmentMgr();

getWriteRichTextMgr

Creates a RichText manager object for writing one or more rich text fields.

Parameters

options {Object}

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

Return Value

A writable rich text manager object. See Writing rich text for details on writing to the stream.

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);
WriteRichTextMgr rtWriteMgr = client.getWriteRichTextMgr();

readDocuments

Reads all documents matching a query string. For the query syntax, see Domino Query Langauge.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.

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

  • 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.

  • itemNames {Array<string>} An optional array of item names. Use this option to read selected items. The default is to read no document items.

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

  • count {number} An optional count of the maximum number of documents to read.

    Note: If you don't specify the optional count, the default value is 100. The "DOCUMENT LIMITS" configuration setting determines the maximum number of documents that can be read, up to 1000.

  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.

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

  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

  • canonicalFormat {boolean} An optional boolean value used to return item properties in canonical format, as objects. See Reading items in canonical format for details.

  • duplicateItems {boolean} An optional boolean value used to return duplicate items. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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);

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

List<Document> responseDocs = client.readDocuments(query).get();

readDocumentsByUnid

Reads multiple documents by UNID. To read a single document, see Document::read.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • itemNames {Array<string>} An optional array of item names. Use this option to read selected items. The default is to read no document items.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • readAttachmentSummaries {boolean} An optional boolean value specifying whether to read attachment summaries as described in @attachments.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
  • canonicalFormat {boolean} An optional boolean value used to return item properties in canonical format, as objects. See Reading items in canonical format for details.
  • duplicateItems {boolean} An optional boolean value used to return duplicate items. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Document> responseDocs = client.readDocumentsByUnid(
  Sets.newHashSet(
  "28438659F50E2637852582C600038599",
  "5B5544335FA7D893852582C60003859A")).get();

getReadAttachmentMgr

Reads attachments from all documents matching a query string.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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.
  • fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.
  • chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{ReadAttachmentMgr} A ReadAttachmentMgr object of a readable attachment manager. See Reading attachments for details on reading from the manager.

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);
ReadAttachmentMgr readAttachmentMgr = client.getReadAttachmentMgr("Form = 'Contact' and LastName = 'Aardman'");

getReadAttachmentMgrByUnid

Reads attachments from a set of documents specified by UNID.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are streamed. If not specified, ALL attachments are streamed.
  • chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

{ReadAttachmentMgr} ReadAttachmentMgr object of a readable attachment manager. See Reading attachments for details on reading from the manager.

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);
ReadAttachmentMgr readAttachmentMgr =
  client.getReadAttachmentMgrByUnid(Sets.newHashSet("28438659F50E2637852582C600038599",
                                                    "5B5544335FA7D893852582C60003859A"));

getReadRichTextMgr

Reads rich text from all documents matching a query string.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.
  • fields {Array<string>} REQUIRED - An array of rich text item names. Repeating items with the same name will be concatenated into a single stream without the data type word.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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.
  • chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

A read rich text manager object. See Reading Rich Text for details on reading from the stream.

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);

ErrorHandler<DocumentException> errHandler = new ErrorHandler<DocumentException>() {
  @Override
  public void onErrorHandler(DocumentException dominoDbException) {
   System.out.println("Exception" + dominoDbException.getMessage());
  }
};

Database client = server.useDatabase(TARGET_DATABASE);

OptionalChunkSizeKb chunkSize = new OptionalChunkSizeKb(32);

ReadRichTextMgr readManager = client.getReadRichTextMgr(
  query: "Form = 'Contact' and LastName = 'Aardman'",
  Sets.newHashSet("Body", "RichText2", "RichText3"),
  errHandler,
  chunkSize);

getReadRichTextMgrByUnid

Reads rich text from a set of documents specified by UNID.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • fields {Array<string>} REQUIRED - An array of rich text item names. Repeating items with the same name will be concatenated into a single stream without the data type word.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • chunkSizeKb {number} An optional stream chunk size in kilobytes. If the specified number is not allowed by the server, the closest allowable chunk size is used.

Return Value

A read rich text manager object. See Reading Rich Text for details on reading from the stream.

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);

OptionalChunkSizeKb chunkSize = new OptionalChunkSizeKb(32);

ReadRichTextMgr readManager = client.getReadRichTextMgrByUnid(
  Sets.newHashSet("28438659F50E2637852582C600038599", "5B5544335FA7D893852582C60003859A"),
  Sets.newHashSet("Body", "RichText2", "RichText3"),
  chunkSize);

deleteDocuments

Deletes all documents matching a query string.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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. See readDocuments for details.
  • start {number} An optional zero-based document start index.
  • count {number} An optional count of the maximum number of documents to delete.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Document> responseDocs = client.deleteDocuments("Form = 'Contact' and LastName = 'Aardman'").get();

deleteDocumentsByUnid

Deletes multiple documents by UNID. To delete a single document, see Document::delete.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Document> responseDocs = client.deleteDocumentsByUnid(
                                Sets.newHashSet("28438659F50E2637852582C600038599",
                                                "5B5544335FA7D893852582C60003859A")).get();

deleteItems

Deletes selected items in all documents matching a query string.

Parameters

options {Object}

  • query {string} REQUIRED -- A query string.
  • itemNames {Array<string>} REQUIRED - An array of item names
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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. See readDocuments for details.
  • start {number} An optional zero-based document start index.
  • count {number} An optional count of the maximum number of documents to process.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<String> itemNames = new ArrayList<String>();
    itemNames.add("EMail");
    itemNames.add("Phone");

List<Document> responseDocs = client.deleteItems("Form = 'Contact' and LastName = 'Aardman'", itemNames).get();

deleteItemsByUnid

Deletes selected items in multiple documents.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • itemNames {Array<string>} REQUIRED - An array of item names
  • accessToken {string} An optional access token. See Act-as-User for details.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<String> itemNames = new ArrayList<String>();
    itemNames.add("EMail");
    itemNames.add("Phone");

List<Document> responseDocs = client.deleteItemsByUnid(
                              Sets.newHashSet("28438659F50E2637852582C600038599",
                              "5B5544335FA7D893852582C60003859A"), itemNames).get();

deleteAttachments

Deletes attachments in documents matching a query string.

Parameters

options {Object}

  • query {string} REQUIRED -- A query string.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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. See readDocuments for details.
  • fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are deleted. If not specified, ALL attachments are deleted.
  • start {number} An optional zero-based document start index.
  • count {number} An optional count of the maximum number of documents to process.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<AttachmentInfo>>} A ListenableFuture resolved with a list of AttachmentInfo.

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);
OptionalFileNames files = new OptionalFileNames(Sets.newHashSet("photo.jpg"));

ListenableFuture<List<AttachmentInfo>> response =
      client.deleteAttachments("Form = 'Contact' and LastName = 'Aardman'",files);

deleteAttachmentsByUnid

Deletes attachments in multiple documents.

Parameters

options {Object}

  • unids {Array<string>} REQUIRED - An array of UNIDs.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • fileNames {Array<string>} An optional array of attachment file names. If specified, only matching attachments are deleted. If not specified, ALL attachments are deleted.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".

Return Value

{ListenableFuture<List<AttachmentInfo>>} A ListenableFuture resolved with a list of AttachmentInfo.

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);
ListenableFuture<List<AttachmentInfo>> response =
                            client.deleteAttachmentsByUnid(
                              Sets.newHashSet("28438659F50E2637852582C600038599",
                                              "5B5544335FA7D893852582C60003859A"));

replaceItems

Replaces selected items in all documents matching a query.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.
  • replaceItems {Object} REQUIRED - An object containing items to replace in all matching documents.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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. See readDocuments for details.
  • start {number} An optional zero-based document start index.
  • count {number} An optional count of the maximum number of documents to process.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
  • duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Item<?>> itemList = new ArrayList<Item<?>>();
    itemList.add(new TextItem("City", "Chelmsford"));
    itemList.add(new TextItem("State", "MA"));
List<Document> responseDocs = client.replaceItems("Form = 'Contact' and LastName = 'Aardman'", itemList).get();

replaceItemsByUnid

Replaces selected items in multiple documents by UNID.

Parameters

options {Object}

  • replaceItemsByUnid {Array<string>} REQUIRED - An array of document
  • accessToken {string} An optional access token. See Act-as-User for details. objects. Each document object must include at least an @unid property.
  • replaceItems {Object} An optional object containing items to replace in all matching documents.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
  • duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Item<?>> itemList1 = new ArrayList<Item<?>>();
    itemList1.add(new TextItem("FirstName", "Aaron"));
    itemList1.add(new TextItem("LastName", "Aardman"));

List<Item<?>> itemList2 = new ArrayList<Item<?>>();
    itemList2.add(new TextItem("FirstName", "Brian"));
    itemList2.add(new TextItem("LastName", "Zelnick"));

List<Item<?>> itemList = new ArrayList<Item<?>>();
    itemList.add(new TextItem("City", "Chelmsford"));
    itemList.add(new TextItem("State", "MA"));

Map<String, List<Item<?>>> replaceInfo = new HashMap<String, List<Item<?>>>();
    replaceInfo.put("F0C617C4AF746BED852582B9006819F9", itemList1);
    replaceInfo.put("3EB633978241DD02852582B9006819FE", itemList2);

List<Document> responseDocs = client.replaceItemsByUnid(replaceInfo, itemList).get();

replaceDocumentsByUnid

Replaces multiple documents.

Parameters

options {Object}

  • documents {Array<Object>} REQUIRED - An array of documents to update. Each document object must include an @unid property.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • computeOptions {Object} An optional object specifying how to compute items on the specified documents. See Compute with form for details.
  • onErrorOptions {string} A optional string specifying what to do when an error occurs. Must be either "ON_ERROR_CONTINUE" or "ON_ERROR_ABORT_REMAINING".
  • duplicateItems {boolean} An optional boolean value used to create duplicate items in the matching documents. See Duplicate items for details.

Return Value

{ListenableFuture<List<Document>>} A ListenableFuture resolved with a list of 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<Item<?>> itemList1 = new ArrayList<Item<?>>();
        itemList1.add(new TextItem("Form", "Contact"));
        itemList1.add(new TextItem("FirstName", "Aaron"));
        itemList1.add(new TextItem("LastName", "Aardman"));
        itemList1.add(new TextItem("City", "Arlington"));
        itemList1.add(new TextItem("State", "MA"));

List<Item<?>> itemList2 = new ArrayList<Item<?>>();
        itemList2.add(new TextItem("Form", "Contact"));
        itemList2.add(new TextItem("FirstName", "Brian"));
        itemList2.add(new TextItem("LastName", "Zelnick"));
        itemList2.add(new TextItem("City", "Andover"));
        itemList2.add(new TextItem("State", "MA"));

Map<String, List<Item<?>>> replaceInfo = new HashMap<String, List<Item<?>>>();
        replaceInfo.put("F0C617C4AF746BED852582B9006819F9", itemList1);
        replaceInfo.put("3EB633978241DD02852582B9006819FE", itemList2);

List<Document> responseDocs = client.replaceDocumentsByUnid(replaceInfo).get();

explainQuery

Explains how a query string is processed.

Parameters

options {Object}

  • query {string} REQUIRED - A query string.
  • accessToken {string} An optional access token. See Act-as-User for details.
  • 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. See readDocuments for details.

Return Value

{ListenableFuture<string>} A ListenableFuture resolved with explanation string

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);

String responseDocs = client.explainQuery("Form = 'Contact' and LastName = 'Aardman'").get();

useAgent

A factory function for instantiating an Agent instance that is bound to a specific agent.

NOTE: This function does not make any requests to Domino for verification of the configuration.

Parameters

  • name {string} The Agent name or alias.

Return Value

An instance of the Agent class

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", "Jone"));
    itemList.add(new TextItem("LastName", "Jonty"));
    itemList.add(new TextItem("State", "MH"));

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

Agent agent = client.useAgent("agent-with-selection-java");

String query = "Form = 'Contact' and State = 'MH'";
OptionalSelection optSelection = new OptionalSelection(query);
OptionalContext optContext = new OptionalContext(createResponse.get().getUnid());

ListenableFuture<AgentRunResponse> response = agent.run(optSelection, optContext);

The Java Agent class has only one run() method and it supports OptionalSelection and OptionalContext as optional arguments.

upsertDocument

UpsertDocument API Searches for a document matching a query string, then updates the selected items. If no document is found, creates a new document with the items instead.

Parameters

  • accessToken {Object} Optional - An optional access token. See OptionalAccessToken for details.
  • query {string} REQUIRED - The query to search the document. The search query must find one document. If it finds multiple documents, upsertDocument fails with NOT_UNIQUE_SEARCH error.
  • document {document} REQUIRED - The document object which will be used for upsert operation.
  • queryArgs {Array<Object>} Optional - An optional array of values to substitute in the query string. See Query arguments for details.
  • queryLimits {Object} Optional - An optional set of limits on the query. See readDocuments for details.
  • computeOptions {Object} Optional - An optional object specifying how to compute items on the specified documents. See Compute with form for details.

Return Value

{ListenableFuture<Document>} A ListenableFuture resolved with a Document.

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"));
String query = "Form = 'Contact' and FirstName = 'Aaron'";
ListenableFuture<Document> response = client.upsertDocument(query, new Document(itemList),
  new ComputeOptions(true, false));

exportDXL

Exports a Domino database to DXL.

Parameters

  • accessToken {string} Optional - An optional access token. See OptionalAccessToken and Act-as-User for details.
  • ExportDXLOptions {object} Optional - An optional value that controls how the export is performed. Must be either "EXPORT_ALL" or "EXPORT_DESIGN".

The following code snippet demonstrates how exportDXLOptions are passed to exportDXL:

  DXLRequestMgr result = client.exportDXL(OptionalArg.ExportDXL.EXPORT_DESIGN);

Return Value

{DXLRequestMgr} A DXLRequestMgr object of a DXL data.

  • If the request or operation fails, the DXLException object shows the details about the failure.

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);
DXLRequestMgr dxlRequestMgr =
        client.exportDXL(errorHandler, OptionalArg.ExportDXL.EXPORT_DESIGN);
InputStream dxlData = dxlRequestMgr.getDXLStream();

getACL

GetACL API returns ACL entries and roles for a given database. Uses a database file path relative to the Domino data directory. Application requires at least Read access to the database.

Parameters

The following code snippet demonstrates how access token is passed to getACL:

  ListenableFuture<GetACLResponse> result = client.getACL(new OptionalAccessToken(<accesstoken>);

Return Value

{ListenableFuture<GetACLResponse>} A ListenableFuture resolved with a GetACLResponse.

Expect these possible sequence of events:

  • If the request or operation fails, the ACLException object shows the details about the failure.

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);
ListenableFuture<GetACLResponse> response = client.getACL();

editACL

EditACL performs following operations:

  • Insert a role in a database ACL.
  • Delete a role from a database ACL.
  • Upsert (update or insert) an ACL entry.
  • Delete an ACL entry.

Uses a database file path relative to the Domino data directory. Application ID/User requires at least Read access to the database.

Parameters

The following code snippet demonstrates how access token is passed to editACL:

  EditACLMgr editMgr = client.editACL(new OptionalAccessToken(accessToken));

Return Value

{EditACLMgr} An EditACLMgr object.

Expect these possible sequence of events:

  • If the request or operation fails, the ACLException object shows the details about the failure.

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> dbRoles = new ArrayList<String>();
dbRoles.add("[testRole1]");
dbRoles.add("[testRole2]");

ACLEntry aclEntry = new ACLEntry("tuser1", ACLEntryType.PERSON, AccessLevel.AUTHOR
        , Sets.newHashSet(Permission.READ_PUBLIC_DOCUMENTS),
        Sets.newHashSet(dbRoles));
editMgr.addDBRole(dbRoles);
editMgr.deleteDBRole(dbRoles);
editMgr.upsertEntry(aclEntry);
editMgr.deleteEntry(aclEntry.getName());

DBOperationResponse response = editMgr.apply().get();

setACL

The setACL API deletes existing database ACL entries and roles and inserts new ones. On successful call to the API will result in database ACL having only passed roles and ACL entries. If permissions are not passed explicitly then default access level based permissions will be assigned.

The application-id or identity derived from the access token must have Manager access to the database.

The setACL API is overloaded.

ListenableFuture<DBOperationResponse>
  setACL(List<ACLEntry> aclEntries, OptionalArg... optionalArgs);

Parameters

  • aclEntries {{List<ACLEntry>}} REQUIRED - An array of unique AclEntry objects.
  • optionalArgs {OptionalAccessToken(String)} Optional - An access token. See OptionalAccessToken for details.

This version of setACL sets only ACL entries.

ListenableFuture<DBOperationResponse> setACL(Set<String> dbRoles, List<ACLEntry> aclEntries,
        OptionalArg... optionalArgs) throws ACLException, InterruptedException

Parameters

  • dbRoles {Set<String>} Optional - An optional array of unique database roles.
  • aclEntries {{List<ACLEntry>}} REQUIRED - An array of unique AclEntry objects.
  • optionalArgs {OptionalAccessToken(String)} Optional - An access token. See OptionalAccessToken for details.

This version of setACL sets database roles and ACL entries.

ListenableFuture<DBOperationResponse> setACL(Set<String> dbRoles, List<ACLEntry> aclEntries,
        ErrorHandler<ACLException> errorHandler,  OptionalArg... optionalArgs)
        throws ACLException, InterruptedException

Parameters

  • dbRoles {Set<String>} Optional - An optional array of unique database roles.
  • aclEntries {{List<ACLEntry>}} REQUIRED - An array of unique AclEntry objects.
  • errorHandler {ErrorHandler<ACLException>} - Optional - An optional object of ErrorHandler<ACLException> type.
  • optionalArgs {OptionalAccessToken(String)} Optional - An access token. See OptionalAccessToken for details.

This version of setACL sets database roles and ACL entries. If any error occurs and if object of ErrorHandler<ACLException> is passed then error can be caught at onErrorHandler() method of ErrorHandler<ACLException> otherwise ACLException will be thrown.

Return Value

All three overload has same return type.

{ListenableFuture<DBOperationResponse>} A ListenableFuture resolved with a DBOperationResponse object.

The requirements to call setACL successfully are:

  1. -Default- must be present in the entries parameter, otherwise the API throws an exception.
  2. At least one ACL entry must have Manager access, otherwise the API throws an exception.
  3. The dbRoles parameter is optional. If specified AclEntry contains the role, then dbRoles parameter is mandatory otherwise the API throws an exception. Role name comparison is case-sensitive.
  4. Role names must be enclosed in [] brackets, e.g. [_ActAsUser].
  5. Specifying permissions is optional. If not specified, default permissions are used. The following combinations of access level and permission are not allowed and throw an exception:
  • Access level: No Access; permission: CREATE_DOCUMENTS
  • Access level: NO Access or Depositor; Permission REPLICATE_OR_COPY_DOCUMENTS without READ_PUBLIC_DOCUMENTS

Caution - To allow the application that is adding entries to access the database after the ACL change other than through the -Default- access, pass its application-id in the aclEntries parameters list.

Example-1 setACL without roles

In this example setACL API is called using certificate for 'CN=IAMAccessor/O=hclpnp' which currently has Manager access in the database ACL. After a successful call to this API, three ACL entries are created and all previous entries and roles are deleted.

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);
ACLEntry defaultUser = new ACLEntry("-Default-", ACLEntryType.UNSPECIFIED, AccessLevel.NO_ACCESS,
         null, null);
ACLEntry iamUser = new ACLEntry("CN=IAMAccessor/O=hclpnp", ACLEntryType.PERSON, AccessLevel.MANAGER,
         null, null);
ACLEntry user1 = new ACLEntry("CN=User1/O=hclpnp", ACLEntryType.PERSON, AccessLevel.DESIGNER,
         null, null);

List<ACLEntry> aclEntries = new ArrayList<ACLEntry>();
aclEntries.add(defaultUser);
aclEntries.add(iamUser);
aclEntries.add(user1);

try {
      DBOperationResponse response = client.setACL(aclEntries).get();
      System.out.println(response.getErrorCode());
    } catch (ACLException | InterruptedException | ExecutionException e) {
      System.err.println(e.getMessage());
    }

Example-2 setACL with roles

In this example, setACL API is called using the certificate for 'CN=IAMAccessor/O=hclpnp' which currently has Manager access in the database ACL. After a successful call to this API, three ACL entries and three roles are created. 'Role1' is selected for 'CN=IAMAccessor/O=hclpnp' and 'Role2' is selected for 'CN=User1/O=hclpnp'.

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<String> dbRoles = new HashSet<String>();
dbRoles.add("[Role1]");
dbRoles.add("[Role2]");

ACLEntry defaultUser = new ACLEntry("-Default-", ACLEntryType.UNSPECIFIED, AccessLevel.NO_ACCESS,
        null, null);
ACLEntry iamUser = new ACLEntry("CN=IAMAccessor/O=hclpnp", ACLEntryType.PERSON, AccessLevel.MANAGER,
        null, Sets.newHashSet("[Role1]"));
ACLEntry user1 = new ACLEntry("CN=User1/O=hclpnp", ACLEntryType.PERSON, AccessLevel.DESIGNER,
        null, Sets.newHashSet("[Role2]"));

List<ACLEntry> aclEntries = new ArrayList<ACLEntry>();
aclEntries.add(defaultUser);
aclEntries.add(iamUser);
aclEntries.add(user1);
try {
      DBOperationResponse response = client.setACL(aclEntries).get();
      System.out.println(response.getErrorCode());
    } catch (ACLException | InterruptedException | ExecutionException e) {
      System.err.println(e.getMessage());
    }

Troubleshooting

Following are the few known errors/exceptions and their cause.

Error: Proton (582)

Error message: You are not authorized to perform that operation

  • Detail error info:
Appliation-id or identity derived from access token(callee) is not Manager.

Error: Proton (1068)

Error message: Access control list must contain at least one Manager

  • Detail error info:
None of the passed ACL entries has the access level Manager.

Error message: Invalid role name or length exceeded

  • Detail error info:
Role name contains invalid character or it has more than 14 characters.

Error message: Missing ACL Entry role [...]

  • Detail error info:
One of the Role name passed in aclEntries is not present in dbRoles or dbRoles is empty.

Error message: ACL permission not supported

  • Detail error info:
An ACL permission was passed that is not supported for the selected access level.
For example, specifying NO_ACCESS and the CREATE_DOCUMENTS permission causes this exception.

GetACLResponse class

GetACL API operation will return object of this class.

getErrorCode

Returns an error code related to success or failure of ACL operations.

Return Value

ErrorCode {int} Returns error code in int.

hasError

Returns true if the response has an error, otherwise false.

Return Value

{boolean} Returns true/false.

getACLEntries

Gets the list of entries in an ACL.

Return Value

{List<ACLEntry>} Returns the list of entries in an ACL.

getDatabaseRoles

Gets the list of roles in a database ACL.

Return Value

{List<String>} Returns the list of roles in a database ACL.

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("testdatabase.nsf");
GetACLResponse response = client.getACL().get();
if (!response.hasError()) {
    System.out.println(response.getDatabaseRoles());
    for(ACLEntry aclEntry : response.getACLEntries()) {
        System.out.println(aclEntry.getName());
        System.out.println(aclEntry.getAccessLevel());
        System.out.println(aclEntry.getACLEntryType());
        for(Permission permission : aclEntry.getPermissions()) {
            System.out.println(permission);
        }
        for (String role : aclEntry.getRoles()) {
            System.out.println(role);
        }
    }
}

ACLEntry class

This class represents the properties of ACL entry.

getName

Gets a name in an ACL.

Return Value

{String} Returns a name in an ACL.

getACLEntryType

Gets the type for a name in an ACL.

ACL entry type can be one of the following:

  • UNSPECIFIED,
  • PERSON,
  • SERVER,
  • MIXED_GROUP,
  • PERSON_GROUP,
  • SERVER_GROUP

Return Value

ACLEntryType Returns the type for name in an ACL.

getAccessLevel

Gets the access level for a name in an ACL.

ACL access level can be one of the following:

  • NO_ACCESS,
  • DEPOSITOR,
  • READER,
  • AUTHOR,
  • EDITOR,
  • DESIGNER
  • MANAGER

Return Value

AccessLevel Returns the access level for a name in an ACL.

getPermissions

Gets the permissions for a name in an ACL.

Permission list values:

  • CREATE_DOCUMENTS
  • DELETE_DOCUMENTS
  • CREATE_PRIVATE_AGENTS
  • CREATE_PERSONAL_FOLDERS_VIEWS
  • CREATE_SHARED_FOLDERS_VIEWS
  • CREATE_LOTUSSCRIPT_JAVA_AGENTS
  • READ_PUBLIC_DOCUMENTS
  • WRITE_PUBLIC_DOCUMENTS
  • REPLICATE_OR_COPY_DOCUMENTS

Return Value

List<Permission> Returns the permissions for a name in an ACL.

getRoles

Gets the roles for a name in an ACL.

Return Value

List<String> Returns the roles for a name in an ACL.

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("testdatabase.nsf");
GetACLResponse response = client.getACL().get();
if (!response.hasError()) {
    System.out.println(response.getDatabaseRoles());
    for(ACLEntry aclEntry : response.getACLEntries()) {
        System.out.println(aclEntry.getName());
        System.out.println(aclEntry.getAccessLevel());
        System.out.println(aclEntry.getACLEntryType());
        for(Permission permission : aclEntry.getPermissions()) {
            System.out.println(permission);
        }
        for (String role : aclEntry.getRoles()) {
            System.out.println(role);
        }
    }
}

EditACLMgr class

Helper class for EditACL.

addDBRole

Adds roles to a database ACL.

Parameters

dbRoles<String> or Collection<String> It accepts a collection of database roles.

deleteDBRole

Deletes roles from a database ACL.

Parameters

dbRoles<String> or Collection<String> It accepts a collection of database roles.

upsertEntry

Upserts (updates or inserts) an ACL entry.

Note:

When entry with the given name already exists:

  • Access level will set to the level provided to API.
  • Permissions will be changed according to the new access level and the permissions list provided to API. If no permissions are provided only default permissions for a particular access level will be set.
  • If provided ACL entry has roles, only those roles will be enabled and all other roles will be disabled. Provided role list should include all roles that need to be enabled.

Parameters

ACLEntry It accepts an ACL entry object.

deleteEntry

Deletes an ACL entry.

Parameters

aclEntryName<String> It accepts an ACL entry name.

apply

Applies operations related to add database roles, delete database roles, upsert ACL entry, and delete ACL entry.

Return Value

ListenableFuture<DBOperationResponse> Returns DBOperationResponse object.

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> dbRoles = new ArrayList<String>();
dbRoles.add("[testRole1]");
dbRoles.add("[testRole2]");

ACLEntry aclEntry = new ACLEntry("tuser1", ACLEntryType.PERSON, AccessLevel.AUTHOR
        , Sets.newHashSet(Permission.READ_PUBLIC_DOCUMENTS),
        Sets.newHashSet(dbRoles));
editMgr.addDBRole(dbRoles);
editMgr.deleteDBRole(dbRoles);
editMgr.upsertEntry(aclEntry);
editMgr.deleteEntry(aclEntry.getName());

ListenableFuture<DBOperationResponse> response = editMgr.apply();
← domino-richtext Referencecom.hcl.domino.db Advanced Topics →