HitResultset Class Reference

The HitResultset class allows comprehensive search operations in Documents and in connected archives. More...

Public Member Functions
	dispose ()
	Free most of the memory of the HitResultset. More...
number	fetchedSize ()
	Get the number of already loaded hits in the set. More...
boolean	fetchNextPage ()
	Load the next page of hits into the Resultset. More...
DocHit	first ()
	Retrieve the first DocHit in the HitResultset. More...
DocHit	getAt (number pos)
	Retrieve the DocHit object at a given position in the HitResultset. More...
number	getColumnCount ()
	Get the number of available columns in the set of hits. More...
number	getColumnIndex (String colName)
	Find the index of a column with a defined name. More...
Array	getColumnNames (boolean local=False)
	List the names of all columns in the set of hits. More...
string []	getHitIds (boolean withServer=true)
	Returns an array with all Hit-Ids (file ids or archive file keys) of the HitResultset. More...
String	getLastError ()
	Function to get the description of the last error (or warning) that occurred. More...
number	getLastErrorCode ()
	Function to get a numeric code of the last error, that occurred. More...
HitResultset	HitResultset (Var searchResources, String filter, String sortOrder, Var hitlist, number pageSize=0, boolean unlimitedHits=false, boolean fullColumnLength=false, boolean withBlobInfo=false)
	Perform a search and create a new HitResultset object. More...
DocHit	next ()
	Retrieve the next DocHit in the HitResultset. More...
number	size ()
	Get the total amount of hits in the set. More...

Detailed Description

The HitResultset class allows comprehensive search operations in Documents and in connected archives.

While the constructor of this class launches a search operation, the created object stores the results and exposes them as a list of DocHit objects. Compared with the classes FileResultset and ArchiveFileResultset this class has got the following characteristics.

• Several filetypes and archives can be searched at one time.
• Extracting archive hits from a HitResultset does not make DOCUMENTS create a temporary DocFile for each hit. This can save a lot of time.
• Objects of this class may allocate large amounts of memory, because they sustain a complete hit list instead of a lean id-list. To save memory, scripts should prefer hit lists with as few columns as possible.
• Search-related errors and warnings do not trigger exceptions. Instead, they are stored inside the object. You can access them with getLastErrorCode() and getLastError() respectively. Advantage: The caller gets the freedom to process the results also after a warning. In this case the hit list maybe incomplete or unsorted.

Since

DOCUMENTS 4.0b

Example:

var searchResources = "Filetype1 \n Filetype2";
var filter = "";
var sortOrder = "";
var myFile;
var myHRS = new HitResultset(searchResources, filter, sortOrder);
if (myHRS.getLastErrorCode() < 0)
{
    util.out(myHRS.getLastError());
}
else
{
    for (var myHit = myHRS.first(); myHit; myHit = myHRS.next())
    {
        myFile = myHit.getFile();
        if (myFile)
            util.out(myFile.getAutoText("id"));
        else
            util.out(myHit.getLastError());
    }
}

Example:

var searchResources = ["$(#STANDARD)\\REGTEST@myeei", "Filetype1@myeas", "Filetype1"];
var filter = "";
var sortOrder = "";
var hitlist = "MYHITLIST";
var pageSize = 3;
var pos = 6;
var unlimitedHits = true;
var fullColumnLength = true;
var myHRS = new HitResultset(searchResources, filter, sortOrder, hitlist, pageSize, unlimitedHits, fullColumnLength);
if (myHRS.getLastErrorCode() < 0)
    throw new Error(myHRS.getLastError());

if (myHRS.size() > pos)
{
    while (pos >= myHRS.fetchedSize())
        myHRS.fetchNextPage();
    var myHit = myHRS.getAt(pos);
    if (myHit)
    {
        if (myHit.isArchiveHit())
            util.out(myHit.getArchiveKey());
        else
            util.out(myHit.getFileId());
    }
}

Example:

var searchResources = "Unit=Default/Instance=Default/View=REGTEST@myeex";
var filter = "";
var sortOrder = "myField+";
var hitlist = "myHitlist";
var pageSize = 10;
var myFile;
var myHRS = new HitResultset(searchResources, filter, sortOrder, hitlist, pageSize);
if (myHRS.getLastErrorCode() < 0)
    throw new Error(myHRS.getLastError());

// Iterate only the hit entries on the first page.
for (var myHit = myHRS.first(); myHit; myHit = myHRS.next())
{
    myFile = myHit.getArchiveFile();
    if (myFile)
        util.out(myFile.getAttribute("Key"));
    else
        util.out(myHit.getLastError());
}

Constructor & Destructor Documentation

HitResultset()

HitResultset HitResultset::HitResultset	(	Var	searchResources,
		String	filter,
		String	sortOrder,
		Var	hitlist,
		number	pageSize = 0,
		boolean	unlimitedHits = false,
		boolean	fullColumnLength = false,
		boolean	withBlobInfo = false
	)

Perform a search and create a new HitResultset object.

Parameters

searchResources	The list of resources to search through. The resource identifiers may be passed either as an array of strings or as an ordinary string with one identifier per line of text. Please read the remarks section about restrictions.
filter	A filter expression. Pass an empty string, if no filter ist required.
sortOrder	A sort expression. Pass an empty string, if no sorting is required.
hitlist	The technical name of a hitlist or an array of field names, which specifies the available columns in the resultset. If the parameter is left empty, Documents tries to choose a hitlist automatically. Details follow in the remarks section. Note: If this parameter is an array of field names, a search in EE.i or EE.x is not allowed and the field names must not contain commas (,).
pageSize	This is a memory-saving and performance-tuning option. If the parameter is zero, Documents will load all available hits at once. If the parameter is a positive value, Documents will initially load only the requested number of hits as a first page. In order to access each further page, a call to fetchNextPage() is necessary. A negative pageSize value will be replaced by the current user's "hits per page" preference setting.
unlimitedHits	A boolean that indicates, if the general hit limitations on filetypes and archives must be ignored. A wasteful use of this option may cause issues with the system performance or situations with low free memory.
fullColumnLength	A boolean that indicates, if the general hit column length limitations must be ignored. The default column length is 50 characters (if not a different value is defined by the property Documents-Settings: MaxHitfieldLength). If a field value exceeds this size, the first 50 characters will be displayed followed by '...'. If the parameter fullColumnLength is set to true, no truncation will be done.
withBlobInfo	A boolean that indicates, if the HitResultset should contain blob-information that can be fetched with DocHit.getBlobInfo()

Remarks

On a failed search request the constructor does not throw errors. To detect this kind of errors scripts should test the object's error state with getLastErrorCode() or getLastError().

Resource identifiers:

A "resource identifier" can be one of the following: [ examples in brackets ]

• a filetype name [ ftOrder ]
• a filetype name for use with an EDA store [ ftOrder@peachitStore1 ]
• a filetype name for use with all EDA stores [ ftOrder@ALLEAS ]
• a EE.x view key [ Unit=Default/Instance=Default/View=Orders@MyEEX ]
• a EE.i archive key [ $(#STANDARD)\ORDERS@STDARC_360 ]

Archive resource identifiers should always get a "@Servername" appendix, though Documents recognizes EE.x and EE.i resources of the primary archive server without that appendix.

Resource ordering and hitlist specification

The resource, which owns a specified hitlist, has to be passed in the first position of the list. Search requests in EE.i/EE.x-archives do not work with a filetype's hitlist. These archives require a hitlist of their own. For this reason, a list of resources of different types must be ordered in the following way: EE.x before EE.i before anything else. Requests, which involve more than one Easy Enterprise server can work only, if a hitlist of the given name exists in each resource of these servers.

Automatic hitlist selection

If the parameter "hitlist" is an empty string, Documents scans the search resources for a named hitlist. If no named hitlist exists, Documents initializes an old-fashioned anonymous hitlist, which is based on the "Display in hit list" option of fields in the Documents Manager and on corresponding options for particular DocFile attributes (title, created, owner, last modified, last editor). An anonymous hitlist does actually not work with EE.x. It partially works with EE.i. In this case, Documents externally uses the setting "CommonDefaultHitlist" of the configuration file "ArchiveXML.ini" and transfers matching columns into the internal hitlist. As long as named hitlists become imported with the archive structure, it does not matter.

Search requests, which involve more than one Easy Enterprise server cannot rely on the automatic selection feature. Scripts should always pass an appropriate hitlist name for these requests.

See also

Using filter expressions with FileResultSets , Filter examples

Since

DOCUMENTS 4.0b

DOCUMENTS 4.0d HF1 new parameter fullColumnLength

DOCUMENTS 5.0 (New option for hitlist parameter: an array of field names instead of a hitlist name)

Member Function Documentation

dispose()

HitResultset::dispose

(

)

Free most of the memory of the HitResultset.

This function explicitly frees the memory used by the object. The Resultset itself becomes empty. All extracted DocHit objects become invalid and must no longer be used. Long-running scripts should use this function instead of waiting for the garbage collector to clean up.

Returns

The function does not return a value.

Since

DOCUMENTS 4.0b

fetchedSize()

number HitResultset::fetchedSize

(

)

Get the number of already loaded hits in the set.

Returns

integer value with the number of hits, which can actually be read from the resultset.

Remarks

If the object has been created with a non-zero page size, this value is often smaller than the total amount of hits.

Since

DOCUMENTS 4.0b

See also

size(), fetchNextPage()

fetchNextPage()

boolean HitResultset::fetchNextPage

(

)

Load the next page of hits into the Resultset.

If the object has been created with a non-zero page size, each call of this function appends another page of hits to the resultset until all hits are loaded.

Returns

The value indicates, if any more hits have been loaded.

Since

DOCUMENTS 4.0b

first()

DocHit HitResultset::first

(

)

Retrieve the first DocHit in the HitResultset.

Returns

DocHit object, null in case of an empty HitResultset

See also

next()

Since

DOCUMENTS 4.0b

getAt()

DocHit HitResultset::getAt

(

number

pos

)

Retrieve the DocHit object at a given position in the HitResultset.

Parameters

pos	Integer position of the hit, beginning with 0

Returns

DocHit object or null if the position is out of bounds.

Remarks

Valid positions range from 0 to fetchedSize()-1.

Since

DOCUMENTS 4.0b

getColumnCount()

number HitResultset::getColumnCount

(

)

Get the number of available columns in the set of hits.

Returns

The number of columns as an Integer.

Since

DOCUMENTS 4.0b

getColumnIndex()

number HitResultset::getColumnIndex

(

String

colName

)

Find the index of a column with a defined name.

Parameters

colName

The name of the column.

Returns

The zero-based index of the column or a -1, which indicates an unknown column name.

Remarks

The function tests for a technical column name prior to a localized name.

Since

DOCUMENTS 4.0b

getColumnNames()

Array HitResultset::getColumnNames

(

boolean

local = False

)

List the names of all columns in the set of hits.

Parameters

local

A boolean option to read the localized names instead of the technical names.

Returns

Array of strings with the column names.

Remarks

If the resultset is bases on an EE.i hitlist, the function usually returns field numbers instead of technical names, because column descriptions of an EE.i hitlist only consist of the field number and a label. The label would not be a reliable identifier of the column.

Columns, which correspond to a DocFile attribute may be given a special constant name instead of the name in an archive's scheme. "TITLE" on EE.x and "110" on EE.i may be presented as "DlcFile_Title", for example.

Since

DOCUMENTS 4.0b

getHitIds()

string [] HitResultset::getHitIds

(

boolean

withServer = true

)

Returns an array with all Hit-Ids (file ids or archive file keys) of the HitResultset.

Parameters

withServer

optional boolean value to indicate, if the archive file keys should include an "@archiveServerName" appendix.

Returns

Array of String with file ids and archive file keys of the HitResultset.

Since

DOCUMENTS 5.0d

Example:

var searchResources = ["Filetype1@myeas", "Filetype1"];
var myHRS = new HitResultset(searchResources, "", "");
util.out(myHRS.getHitIds());

See also

FileResultset.getIds()

getLastError()

String HitResultset::getLastError

(

)

Function to get the description of the last error (or warning) that occurred.

Returns

Text of the last error as String

Since

DOCUMENTS 4.0b

See also

getLastErrorCode()

getLastErrorCode()

number HitResultset::getLastErrorCode

(

)

Function to get a numeric code of the last error, that occurred.

Returns

Integer error code.

Remarks

The value 0 means "no error". Positive values indicate warnings or minor errors, while negative values indicate serious errors. After a serious error no hits should be processed. After a minor error, the resultset may be unsorted or truncated, but the contained data is still valid.

Since

DOCUMENTS 4.0b

See also

getLastError()

next()

DocHit HitResultset::next

(

)

Retrieve the next DocHit in the HitResultset.

Returns

DocHit object, null if either the end of the resultset or the end of the loaded pages is reached.

Remarks

Calls of getAt() do not affect the internal cursor of next().

See also

first()

Since

DOCUMENTS 4.0b

size()

number HitResultset::size

(

)

Get the total amount of hits in the set.

Returns

integer value with the total amount of hits. The value -1 may be returned to indicate, that the search continues in the background, and the final number is not yet known.

Remarks

If the object has been created with a non-zero page size, this value is often greater than the amount of already accessible hits.

Since

DOCUMENTS 4.0b

See also

fetchedSize(), fetchNextPage()