Performing a search operation
Many operations support acting on one or more items in an Encyclopedia volume. To target the items on which to act, you must apply a search condition to the operation. The com.actuate.schemas library contains many special classes for setting a search condition and implementing a search for an item in an Encyclopedia volume.
The Information Delivery API provides three sets of parameters that support searching for the data on which an operation acts. Typically, these parameters apply to operations that select, update, move, copy, or delete Encyclopedia volume items. The parameters are:
Id or IdList
Name or NameList
Search
Using com.actuate.schemas.SelectFiles
Use com.actuate.schemas.SelectFiles to retrieve file properties using the ID or name of a single file or folder, or a list of files or folders, in an Encyclopedia volume. SelectFiles can recursively search all subfolders in a directory. To restrict a search to the items in a single directory, not including subfolders, use GetFolderItems. SelectFiles does not retrieve file or folder content.
SelectFiles supports three types of searches:
Use Name or Id to retrieve a single file or folder.
Use NameList or IdList to retrieve a list of files or folders in a directory.
Use Search to retrieve all files or folders that match a given condition.
The following application derives from the code in the BIRT iHub Integration Technology example applications for the Apache Axis 2 client. In the example application, AcSelectFiles.searchByCondition( ), calls ActuateControl.selectFiles( ), specifying a search condition, and performing the following operations:
Specifies a search condition for the file type using the wildcard, *, to target all files that contain the character, R, as the first character in the file extension.
public class AcSelectFiles {
…
public static String fileType = "R*";
A wildcard is a character used in a search or conditional expression that matches one or more literal characters. Actuate wildcards include the ones in the following list:
? matches any single one- or two-byte character.
# matches any ASCII numeric character [0‑9].
* matches any number of characters.
The wildcard expression in the example targets files in BIRT iHub such as a BIRT executable file with the file extension RPTDESIGN, and a BIRT document file with the file extension RPTDOCUMENT.
Instantiates a FileCondition object, setting the condition to match on FileField.FileType using the wildcard expression.
public static void searchByCondition( ) {
System.out.println("\nThis example demonstrates search by
file type using search condition:\n");
com.actuate.schemas.FileCondition fileCondition =
new com.actuate.schemas.FileCondition( );
fileCondition.setField(com.actuate.schemas.FileField.
FileType);
fileCondition.setMatch(fileType);
Instantiates a FileSearch object, setting the search to the properties specified in the FileCondition object.
com.actuate.schemas.FileSearch fileSearch =
new com.actuate.schemas.FileSearch();
fileSearch.setCondition(fileCondition);
An application sets the search condition for a file using the FileSearch class. FileSearch is a complex data type that contains the list of properties to specify in a file search condition. An application can specify the search condition for a file using one or more of the following fields:
Name
FileType
Description
PageCount
Size
TimeStamp
Version
VersionName
Owner
Use ArrayOfFileCondition to specify multiple search conditions.
Sets up the fetch handle to process the results.
fileSearch.setFetchSize(new Integer(2));
System.out.println("Search fileType = " + fileType + "\n");
String fetchHandle = null;
int fetchCount = 1;
while (true) {
fileSearch.setFetchHandle(fetchHandle);
Makes the call to ActuateControl.selectFiles( ), obtaining the reference to the fetch handle from the SelectFilesResponse object.
com.actuate.schemas.SelectFilesResponse selectFilesResponse =
actuateControl.selectFiles(fileSearch, null, null);
fetchHandle = selectFilesResponse.getFetchHandle( );
A fetch handle indicates that the number of items in the result set exceeds the fetch size limit. A fetch handle returns as a parameter in the response to a Select or Get request, such as SelectFiles or GetFolderItems.
Use the fetch handle to retrieve more results from the result set. In the second and subsequent calls for data, you must specify the same search condition that you used in the original call. All Get and Select requests, except SelectFileType, support the use of a fetch handle.
Continues processing until there are no more results, printing an appropriate output message.
System.out.println("\n Fetch Size = " +
fileSearch.getFetchSize( )
+ "; Fetch Count = " + fetchCount++ + "\n");
if (fetchHandle == null)
break;
}
}
Using ResultDef
Use a ResultDef parameter to specify the object properties to retrieve from a search. The properties you set in ResultDef depend on the type of item. For example, if the item is a file or folder, you can retrieve the file or folder name, ID, description, date of creation or last update, owner, and version name and number.
ActuateControl.selectFiles( ) specifies and retrieves a list of file properties using a ResultDef parameter by performing the following tasks:
Sets up the ResultDef String array containing the list of file properties.
public com.actuate.schemas.SelectFilesResponse selectFiles(
com.actuate.schemas.FileSearch fileSearch,
String name,
ArrayOfString nameList) {
com.actuate.schemas.ArrayOfString resultDef =
newArrayOfString(
new String[] {
"Description",
"FileType",
"Id",
"Name",
"Owner",
"PageCount",
"Size",
"TimeStamp",
"UserPermissions",
"Version",
"VersionName" });
Instantiates the SelectFiles object.
com.actuate.schemas.SelectFiles selectFiles =
new com.actuate.schemas.SelectFiles( );
Selects files based on a file name, list of file names, or uses com.actuate.schemas.ArrayOfString as a ResultDef parameter to specify the file properties to retrieve.
selectFiles.setResultDef(resultDef);
If not null, sets the reference to either the search object, file name, or list of file names, depending on which parameter ActuateControl.selectFiles( ) receives.
if (fileSearch != null)
selectFiles.setSearch(fileSearch);
else if (name != null)
selectFiles.setName(name);
else if (nameList != null)
selectFiles.setNameList(nameList);
Makes the com.actuate.schemas.SelectFiles call using the proxy.
com.actuate.schemas.SelectFilesResponse selectFilesResponse = null;
try {
selectFilesResponse = proxy.selectFiles(selectFiles);
Loops through the SelectFileResponse item list, printing the file names and list of properties.
com.actuate.schemas.ArrayOfFile itemList =
selectFilesResponse.getItemList( );
com.actuate.schemas.File[ ] files = itemList.getFile( );
if (files != null) {
for (int i = 0; i < files.length; i++) {
printFile(System.out, files[i]);
}
}
} catch (RemoteException e) {
System.out.println("error !!!");
e.printStackTrace();
}
return selectFilesResponse;
}
The Java application writes the messages to a command prompt window when an Encyclopedia volume login succeeds and the select files operation completes.