com.hcl.domino.dql.QueryResultsProcessor Maven / Gradle / Ivy
/*
* ==========================================================================
* Copyright (C) 2019-2022 HCL America, Inc. ( http://www.hcl.com/ )
* All rights reserved.
* ==========================================================================
* Licensed under the Apache License, Version 2.0 (the "License"). You may
* not use this file except in compliance with the License. You may obtain a
* copy of the License at .
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
* ==========================================================================
*/
package com.hcl.domino.dql;
import java.io.Reader;
import java.io.Writer;
import java.util.Collection;
import java.util.Set;
import com.hcl.domino.data.Database;
import com.hcl.domino.data.IDTable;
/**
* Aggregates, computes, sorts, and formats collections of documents across any
* set of Domino databases.
*/
public interface QueryResultsProcessor {
public enum Categorized {
TRUE,
FALSE
}
public enum Hidden {
TRUE,
FALSE
}
/**
* Results processing options
*/
public enum QRPOptions {
/** returns the UNID instead of noteid */
RETURN_UNID,
/** returns the replicaid instead of db filepath */
RETURN_REPLICAID
}
public enum SortOrder {
UNORDERED(0),
ASCENDING(1),
DESCENDING(2);
private final int m_value;
SortOrder(final int value) {
this.m_value = value;
}
public int getValue() {
return this.m_value;
}
}
/**
* Convenience method to add an unsorted column to the processor
*
* @param name programmatic column name
* @return this instance
*/
default QueryResultsProcessor addColumn(String name) {
return addColumn(name, "", "", SortOrder.UNORDERED, Hidden.FALSE, Categorized.FALSE);
}
/**
* Provides Domino formula language to override the data used to generate values
* for a
* particular sort column and an input collection or set of collections. Since
* input collections
* can be created from different databases, design differences can be adjusted
* using addFormula
* to have homogenous values in the output.
*
* @param formula Formula language string to be evaluated in order to supply
* the values for a sort column
* @param columnname String value responding the programmatic name of the sort
* column whose values are to be generated using the formula
* language supplied
* @param resultsname Used to specify the input collection names to which will
* use the formula language to generate sort column values.
* Wildcards may be specified to map to multiple input
* collection names.
* @return this instance
*/
QueryResultsProcessor addFormula(String formula, String columnname, String resultsname);
/**
* Adds note ids from a database to the query results processor
*
* @param parentDb database that contains the documents
* @param noteIds note ids, e.g. an {@link IDTable}
* @param resultsname A unique name (to the QueryResultsProcessor instance) of
* the input. This name is used in returned entries when the
* origin of results is desired and in addFormula method
* calls to override the data used to create sorted column
* values.
* @return this instance
*/
QueryResultsProcessor addNoteIds(Database parentDb, Collection noteIds, String resultsname);
/**
* Creates a single column of values to be returned when
* {@link QueryResultsProcessor} is executed. Column values can be generated from a field
* or a formula. Sorting order, categorization and hidden attributes determine the
* returned stream of results entries.
* Columns span all input result sets and databases taking part in the {@link QueryResultsProcessor}.
* Execute calls in the {@link QueryResultsProcessor} require at least one column to be specified.
*
* @param name The unique (within a QueryResultsProcessor instance)
* programmatic name of the column. If there is no override
* using the addFormula method call, the name provided will
* be treated as a field name in each database involved in
* the QueryResultsProcessor object. In JSON output, the
* name value is used the element name for each returned
* entry.
* Values in the name field can specify aggregate
* functions. These functions require categorized columns
* and return computed numerical values across sets of
* results within a category. For aggregate functions
* requiring a name as an argument, the name can be
* overridden just as for a name without an aggregate
* function. For more information on aggregate functions,
* see the description of the isCategorized parameter.
* @param title The display title of the column. Used only in generated
* views, the title is the UI column header.
* @param formula Formula language string to serve as the default means of
* computing values for the column. If not supplied and if
* not overridden by an addFormula value, the name argument
* is treated as a field name. The precedence of supplying column values is:
*
* - AddFormula Formula Language override
* - Formula argument of the AddColumn method
* - Use the name argument of the AddColumn method as a database field name
*
* If supplied, the Formula Language provided is applied to the column
* across all results added using addCollection or addDominoQuery.
* Formulas are not allowed on columns with aggregates.
* @param sortorder A constant to indicate how the column should be sorted.
* Values are sorted case and accent insensitively by
* default. Multiple sort columns can have sort orders, and
* each order specified is sequentially applied in the
* order of addSortColumn calls. Field lists
* (multiply-occurring field values) are compared processed
* using field occurrences from first to last sequentially.
* @param ishidden Sorts by a column value without returning the value. If
* true, the column cannot have a sort order of
* {@link SortOrder#UNORDERED} and cannot have an
* iscategorized value of true.
* @param iscategorized Categorized columns have a single entry returned for
* each unique value with entries containing that value
* nested under it. In JSON results, these nested entries
* are represented in arrays under each categorized unique
* value.
* Multiply-occurring fields (i.e. lists) are not allowed
* to be categorized.
* A categorized column creates values for any preceding
* uncategorized column in addition to the categorized
* column. Categorized columns can nest to create
* subcategories.
* @return this instance
*/
QueryResultsProcessor addColumn(String name, String title, String formula, SortOrder sortorder,
Hidden ishidden, Categorized iscategorized);
/**
* Processes the input collections in the manner specified by the Sort Columns,
* overriding
* field values with formulas specified via addFormula calls, and returns JSON
* output.
*
* The JSON syntax produced by {@link QueryResultsProcessor} execution conforms
* to JSON RFC 8259.
* All results are output under the “StreamedResults” top element key. For
* categorized results,
* all nested details are output under the “Documents” key.
* Special keys “@nid” for NoteID and “@DbPath” are output so results can be
* acted upon on a document basis.
* Fields that are lists on documents (multiply-occurring) are output as JSON
* arrays of like type.
*
* @param appendable the execution result is written in JSON format into this
* {@link Appendable} in small chunks (e.g. a {@link Writer} or {@link StringBuilder}
* @param options options to tweak the JSON output or null/empty for default
* format
*/
void executeToJSON(Appendable appendable, Set options);
/**
* Processes the input collections in the manner specified by the Sort Columns,
* overriding
* field values with formulas specified via addFormula calls, and returns JSON
* output.
*
* The JSON syntax produced by {@link QueryResultsProcessor} execution conforms
* to JSON RFC 8259.
* All results are output under the “StreamedResults” top element key. For
* categorized results,
* all nested details are output under the “Documents” key.
* Special keys “@nid” for NoteID and “@DbPath” are output so results can be
* acted upon on a document basis.
* Fields that are lists on documents (multiply-occurring) are output as JSON
* arrays of like type.
*
* @return reader to receive the the JSON data
* @param options options to tweak the JSON output or null/empty for default
* format
*/
Reader executeToJSON(Set options);
/**
* Saves sorted QueryResultsProcessor results to a "results view" in a database.
* Processes the input collections in the manner specified by the Sort Columns,
* overriding field values with formulas specified via addFormula calls.
* Creates a results view in a host database and returns note id of the View.
*
* Results views created using the ExecuteToView method have the following distinctive
* characteristics.
*
* To open and manipulate results views using the HCL Notes® client or to write application
* code that utilizes it, it's important to understand these characteristics.
*
* Results views are created and persist in a database that you choose. Using a separate,
* non-production database is recommended. Doing so avoids unnecessary, routine database
* processing and also avoids user confusion over the views, which are not standard views.
*
* Results views are generated programmatically, so they are designed to be discarded after use. Therefore:
*
* - They do not refresh automatically. If you want more recent data, you need to delete the old view using a method to remove in the View class or by running updall with the -Tx option, and then recreate and repopulate the view.
* - They are automatically deleted during updall and dbmt task maintenance after their expiration time elapses.
*
* Results views contain unique NoteIDs that cannot be referenced. Therefore:
*
* - They do not generate document properties data in the Notes client.
* - You can't open them using normal mouse gestures in the Notes client.
* - You can't use full text indexing to search them; they are the results of such searches.
* - You can use API calls that use those NoteIDs only within the context of the results views.
* - They include hidden columns that contain the database path and the true NoteID for each originating document. You can access this information using view column processing.
*
* Security for results views is implemented at the view level:
*
* - By default, only the person or server creating the view can read the view data.
* - You can use the Readers parameter to define a reader list.
* - A person or server with access to the view gets access to all document details and aggregate values; there is no mechanism to restrict this access.
*
* Domino processing of results views is otherwise typical.
*
* You can use Domino Designer to edit results views, with the exception of selection
* criteria and view formulas, which are specified when the views are created.
*
* @param viewName The name of the results view to create and populate.
* @param hoursUntilExpire The time, in hours, for the view to be left in the host database. If not specified, it expires in 24 hours. You can extend the expiration time using the updall or dbmt tasks.
* @param readers These define the allowed Readers for the documents in the View (usernames and groups). Will be converted to canonical format
* @return view note id
* @since 1.8.8, requires JNX running against a Notes/Domino R12.0.1 environment
*/
int executeToView(String viewName, int hoursUntilExpire, Collection readers);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy