executeToView (QueryResultsProcessor - Java)

Saves QueryResultsProcesser 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 View object.

From Domino 14.0.0 onwards, you have the ability to customize the design of a created view by specifying a view name and database to copy the design from. If the source view includes a column named $QRPDefaultColumn, this column's design will be used for any new columns added by the .addColumn() method. Otherwise, the design of the last unhidden column will be used. To override the properties of one of the specified view's columns, you can call .addColumn() with the name of that column. The specified view's column formulae will be used, unless overridden by the formula argument of .addColumn() or by .addFormula(). The specified view remains unchanged and is copied, resulting in the creation of a new view.

Defined in

QueryResultsProcessor
Note: executeToView is new in V12.0.1

Syntax

public View executeToView(String name)
     throws NotesException;
public View executeToView(String name, int expirehours)
     throws NotesException;
public View executeToView(String name, int expirehours, String reader)
     throws NotesException;
public View executeToView(String name, int expirehours, java.util.Vector readerlist)
     throws NotesException;
public View executeToView (String name, int expirehours, java.util.Vector readerlist, Database DesignSrcDB, String DesignSrcViewName) 
     throws NotesException;

Parameters

String name

The name of the results view to create and populate.

int expirehours

The time, in hours, for the view to be left in the host database. If not specified, the view expires in 24 hours. You can extend the expiration time using the updall or dbmt tasks. 

String reader

The name of one additional user or group to be granted read access to the results view. The value must be in canonical format.

java.util.Vector readerlist

A string vector of names to be granted read access to the results view. The values must be in canonical format.

Database DesignSrcDB

The database where DesignSrcViewName is stored. If null, the function will check the database associated with the calling object.

String DesignSrcViewName

The name of the view whose design to copy. Use the specified view as the source design for the QRP view to be created. If null or empty, a default design is used.

Usage

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 String reader or java.util.Vector readerlist 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.

Note: Use the Domino Show database command with the -e option to list the size and expiration time of each results view in a database.

Example 1: Using executeToView

 
Vector <String> readersvec = new Vector <String>();
readersvec.add(“CN=User1 UserLN1/O=MYORG”);
readersvec.add(“CN=User2 UserLN2/O=MYORG”);
readersvec.add(“PrivilegedGroup”);
readersvec.add(“CN=User3 UserLN3/O=MYORG”);

"

/* catch any NotesException below */
try {
     Database mydb = session.getDatabase(“mydb.nsf”);
     QueryResultsProcessor qrp = mydb. createQueryResultsProcessor();

// .. addColumn, addDominoQuery, addFormula, etc.

View myview = qrp.executeToView(theQRP.QPRName, 2, readersvec);

// .. view processing
}           
catch (NotesException ne)
{
     ne.printStackTrace();           
     System.out.println("Bad Return " + ne.getMessage());
}

Example 2: Using the invisible view columns $DBPath and $NoteID

 
/* catch any NotesException below */
try {
     Vector vcn = myview.getColumnNames(), v = null;
     ViewEntryCollection vec = m_view1.getAllEntries();
     ViewEntry ve = vec.getFirstEntry();
     int colct = myview.getColumnCount();
     int pathelem = -1, nidelem = -1;
     String noteID = null;           

/* If unknown find the Vector elements for the database path and noteid */
for (int j = 0; j < vcn.size(); j++)
{
     String nm = vcn.elementAt(j).toString();
     if (nm.compareToIgnoreCase("$DBPath") == 0)
          pathelem = j;
     else if (nm.compareToIgnoreCase("$NoteID") == 0)
          nidelem = j;
}

// Walk through the view entries      
while (ve != null)
{
     ve2 = ve;
     // Get current view entry values
     v = ve.getColumnValues();
     dbpath = v.elementAt(pathelem).toString();
     noteID = v.elementAt(nidelem).toString();

… // open the database, open the document and process as desired
     v = null;
     ve = vec.getNextEntry();
     ve2.recycle();
     ve2 = null;
}

}           
catch (NotesException ne)
{
     ne.printStackTrace();           
     System.out.println("Bad Return " + ne.getMessage());
}

Example 3: Creating a view with a specific design

QueryResultsProcessor qrp = db.createDominoQuery();

// SrcDB contains a view named “MyCoolView” which will serve as the template for the design of our newly created view 
Database SrcDB = session.GetDatabase(“serverName”, “DBName”);

// oldColumn already exists in MyCoolView, we are renaming the title here
qrp.addColumn(“oldColumn”, “newTitle1”);

// newColumn does not exist in MyCoolView, we create it here
qrp.addColumn(“newColumn”, “newTitle2”)

// call executeToView where SrcDB is the DB where MyCoolView is stored
// MyCoolView contains columns with custom colors and fonts
View myview = qrp.executeToView(“NewQRPViewName”, 0, null, SrcDB, “MyCoolView”);