Searching a Resource Set

This chapter explains how to search the contents of a resource set. It contains the following sections:

About the Search tab

The Search tab provides a facility for searching for objects within a resource set. The Search tab lets you specify search filters for locating objects. You can search by file name or directory name, or look for particular string patterns within files in a resource set. When you've found the objects you're looking for, you can make any changes you want, or save the search as a view.

The Search tab provides complete support for regular expression searches.

For more information For syntax and reference information on regular expressions, see the section on regular expressions for text searches in Utility Tools.

Searching a resource set

Procedure To search a resource set:

In the exteNd Director Navigation Pane, click the Resources tab.
Click the Search tab.

Specify the following:

Field	What to specify
Resource Set	The target resource set for the search operation.
File Name	A regular expression that specifies the list of file names to search for.
Directory	A regular expression that specifies which directories should be included in the search. If you want to search only a single directory within the resource set, select from the dropdown list.
Data	A regular expression that specifies a string pattern to search for within files in the target resource set.

If you specify values for multiple fields, the field values are combined together in an AND operation.

Click Search.

The Search tab displays the list of files that match the search filter, organized by folder. For example, the following search locates all HTML source files that contain the string help:

Items that were read from disk are editable and appear in black. Items that were read from JAR files are not editable. These items appear in blue and are marked with RO (read-only).

Procedure To clear the search criteria:

In the Search tab, click the Clear button.

Procedure To open an item displayed in the Search tab:

Double-click the item in the Search tab.

The source file editor displays the contents of the file, and the Relationship Viewer shows one or more relationships that are specific to the type of file you opened.

For more information on using the Relationship Viewer, see Using the Relationship Viewer.

Saving a search as a view

If you execute the same search operation frequently, you may want to consider saving the search as a view. That way you can execute the search as often as you like without having to specify the search criteria.

When you save a search as a view, the Search tab creates a view definition file in the my-views folder within the resource set. The view definition file is an XML file that specifies which items should be included in the view.

Creating a view manually You can also create a view by manually editing a view definition file. For more information on defining views manually, see Defining custom views.

Procedure To save a search as a view:

In the Search tab, click Save.

The Save dialog displays:
Specify a name for the view definition XML file.
Click Save.

Working with the Search API

The Search tab uses the underlying Search API provided with exteNd Director. For many applications, this search facility is satisfactory. But sometimes you may also want to search the contents of a resource set programmatically. To do this you need to use the following objects in the Search API:

Object	Description	Implementation class(es)
Search object	Performs the search operation. Returns a Vector of resource elements (EboResourcElement objects) that match the search criteria.	EboResourceSearch
Search template	Defines the pattern or set of characteristics that will be used to filter the search.	EboResourceElementTemplate
Search comparator	Compares the template to the target object in the resource element.	EboResourceElementComparator EboResourceClassElementComparator EboResourceREGEXPElementComparator

All of the search implementation classes are located in the com.sssw.fw.resource.search package.

How it works The search object performs the search operation by iterating through the target objects in the resource set, comparing each object with the search template. The search template defines the pattern or characteristic that will be used to filter the search. For example, the search template can specify a file name, directory name, disk path, or string of bytes to search for. When the search is performed, the template is compared against each target object in the resource element. If the objects are equivalent, the target object is added to the search results. The search object returns the results in a Vector of resource element objects.

Ways to set the search template There are several ways to set the search template object for a search:

Use the internal search template object
Create your own search template object and pass it to the search object
Pass a DOM object directly to the search object

The search comparator compares the template against the target object to see if there's a match. The Search API includes three search comparators:

Comparator	Description
EboResourceElementComparator	Supports comparison using the indexOf() method on the String class.
EboResourceClassElementComparator	Supports comparison using the indexOf() method on the String class. This comparator filters out items that end in .class.
EboResourceREGEXPElementComparator	Supports comparison using regular expressions.

Example 1: using the internal search template object

Suppose you want to search for all XML files in a resource set that contain the string FireRule. One way to do this would be to use the internal template object built into the EboResourceSearch class. Here's a code snippet that shows how you might do this:

  EboResourceSearch resourceSetSearch = new EboResourceSearch();
  resourceSetSearch.setComparator( 
      new EboResourceREGEXPElementComparator() );
  resourceSetSearch.getTemplate().setFileName( ".xml" );
  resourceSetSearch.getTemplate().setBytes( "FireRule" );
  Vector v = resourceSetSearch.search( resourceSet );

This code example uses EboResourceREGEXPElementComparator as the search comparator. This is the search comparator for regular expression comparisons.

Example 2: creating your own search template object

You can also define your own search template object and instruct the search object to use that instead of the built-in search template object. In this case you instantiate the template object, fill in the template values you want to use, and then pass the object to the search object. The following example shows how you might do this:

  EboResourceSearch resourceSetSearch = new EboResourceSearch();
  resourceSetSearch.setComparator( 
      new EboResourceREGEXPElementComparator() );
  EboResourceElementTemplate template = new EboResourceElementTemplate();
  template.setFileName( ".xml" );
  template.setBytes( "FireRule" );
  resourceSetSearch.setTemplate( template );
  Vector v = resourceSetSearch.search( resourceSet );

Example 3: serializing a search request

If you want to be able to save a search as a view, you need to serialize the search request. To do this you need to build XML that conforms to the following DTD:

  <?xml version="1.0" encoding="UTF-8"?>
  <!ELEMENT search EMPTY>
  <!ATTLIST search
    bytes CDATA #IMPLIED
    directoryName CDATA #IMPLIED
    diskPath CDATA #IMPLIED
    javaPackage CDATA #IMPLIED
    fileName CDATA #IMPLIED >

Suppose you want to search for all XML files in a resource set that contain the string FireRule. The XML string required for this search would be:

  <search fileName=".xml" bytes="FireRule" />

To build this XML string programmatically, you could use the following code:

  EboResourceSearch resourceSetSearch = new EboResourceSearch();
  resourceSetSearch.setComparator( 
     new EboResourceREGEXPElementComparator() );
  resourceSetSearch.setTemplate( "<search fileName=\".xml\" bytes=\"FireRule\" />" );
  Vector v = resourceSetSearch.search( resourceSet );