Class: TMultipleRootLocator

Declaration: MultipleRootLocator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TMultipleRootLocator is the class used for locating data files. It serves as a mechanism to locate these data files within possibly multiple parallel file hierarchies. It is capable of looking in each of these hierarchies, locating the first file of a given name or all of them, and providing the results to the client with or without duplicate named entities. It is merely a wrapper on the standard File system interface functionality. This class doesn't return subsystem-specific resources, such as fonts or transcoding data files. It only returns Pluto File system entities. Specific subsystems can do whatever they need to do to extract their information from these files, from reading the stream of filed data to reading user-defined properties.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TMultipleRootLocator::TMultipleRootLocator

TMultipleRootLocator (const TPathName & relativePath, ESearchMode recursive =kNonRecursive, const TPropertyQuery & =kNoQuery)
TMultipleRootLocator (const TPathName & relativePath, const TSequenceOf < TDirectory > & rootList, ESearchMode recursive =kNonRecursive, const TPropertyQuery & =kNoQuery)

Interface Category:

API.

Purpose:

Constructor that takes a relative path (which should already be localized) telling where to search for resources. This relative path is used in each of the roots in the default root list.

not

Constructor that takes a relative path (which should already be localized) telling where to search for resources. This relative path is used in each of the roots in the default root list.

not

Calling Context:

Called to construct a TMultipleRootLocator with the specified arguments.
Called to construct a TMultipleRootLocator with the specified arguments.

Parameters:

const TPathName & relativePath -The relative path (which should already be localized) telling where to search for resources.
ESearchMode recursive =kNonRecursive -The search mode (recursive or nonrecursive). If recursive, the locator will search depth-first under the relative path.
const TPropertyQuery & =kNoQuery -The query used to match against items under the relative path, for example, kNoQuery, specifying that all items should match and be returned, or kReturnOnlyFiles, specifying that only TFile items should be returned.
const TPathName & relativePath -The relative path (which should already be localized) telling where to search for resources.
const TSequenceOf < TDirectory > & rootList -The root list to be used.
ESearchMode recursive =kNonRecursive -The search mode (recursive or nonrecursive). If recursive, the locator searches depth-first under the relative path.
const TPropertyQuery & =kNoQuery -The query used to match against items under the relative path, for example, kNoQuery, specifying that all items should match and be returned, or kReturnOnlyFiles, specifying that only TFile items should be returned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::~TMultipleRootLocator

virtual ~ TMultipleRootLocator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::FindFirstByName

virtual TFileSystemEntity FindFirstByName (const TFileSystemEntityName & theName)

Interface Category:

API.

Purpose:

Returns the first matching File system entity within any of the roots in the root list that matches both the query (supplied at construction time) and the specified name. (Note: TFileSystemEntityName is also known as TStandardText.) This is the fastest function provided by the resource locator for locating a resource. A recursive search is performed, if requested at construction time.

Calling Context:

Call this function directly.

Parameters:

const TFileSystemEntityName & theName -The name of the File system entity being searched for.

Return Value:

The first matching File system entity within any of the roots in the root list that matches both the query (supplied at construction time) and the specified name.

Exceptions:

Throws TMultipleRootLocatorException::kNamedEntityNotFound if no matching entity is found. Non-existent root directories or relative path directories do not cause an exception.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::FindAllByName

virtual unsigned long FindAllByName (const TFileSystemEntityName & theName, TSequenceOf < TFileSystemEntity > & theResult)

Interface Category:

API.

Purpose:

Fills in the theResult argument with all File system entities within any of the roots in the root list that match both the query (supplied at construction time) and the specified name. The caller adopts the storage. (Note that TFileSystemEntityName is also known as TStandardText.) FindAllByName does not empty the theResult argument first. The matching items are added to the sequence in the order theyÕre found in the root list. The number of added entities is returned (including zero). A recursive search is performed, if requested at construction time.

Calling Context:

Call this function directly.

Parameters:

const TFileSystemEntityName & theName -The name of the File system entity to search for.
TSequenceOf < TFileSystemEntity > & theResult -The sequence to which are added all File system entities within any of the roots in the root list that match both the query (supplied at construction time) and the specified name. If the sequence supplied is a sorted sequence with a specific type of sorting operation, then the results are ordered accordingly.

Return Value:

The number of added entities.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::FindAll

virtual unsigned long FindAll (TSequenceOf < TFileSystemEntity > & theResult)

Interface Category:

API.

Purpose:

Fills in the theResult argument with all matching File system entities within any of the roots in the root list that match the query supplied at construction time. The caller adopts the storage. FindAll does not empty the theResult argument first. The matching items are added to the sequence in the order they are found in the root list. The number of added entities is returned (including zero).

Calling Context:

Call this function directly.

Parameters:

TSequenceOf < TFileSystemEntity > & theResult -The sequence to which are added all File system entities within any of the roots in the root list that match the query supplied at construction time. If the sequence supplied is a sorted sequence with a specific type of sorting operation, then the results are ordered accordingly.

Return Value:

The number of added entities.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::GetWritableDirectory

virtual TDirectory GetWritableDirectory (bool create =true)

Interface Category:

API.

Purpose:

Returns a TDirectory entity corresponding to the relative path specified in the constructor. The directory that is returned is a subdirectory of the first root in the root list. If this directory does not exist, it and any necessary parent directories are created if the create flag is true. For example, if theLocator is constructed with a relative path name of RuntimeEnv/Data/WorkspaceData and theLocator.GetWritableDirectory is called, then the returned TDirectory object refers to that subdirectory from the first root in the userÕs root list. The subdirectory is created if it doesn't exist unless you override the default value for that flag. The "writable" part of this refers to the fact that some roots in the userÕs root list might be shared and read-only, but the first root is always specific to this user and writable.

Calling Context:

Call this function directly.

Parameters:

bool create =true -If true, and the directory doesn't exist, it and any necessary parent directories will be created.

Return Value:

A TDirectory entity corresponding to the relative path specified in the constructor.

Exceptions:

Throws TMultipleRootLocatorException::kWritableRootNotFound if create is false and the directory can't be found, or if create is true and the directory cannot be created.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::GetDefaultRootList

static void GetDefaultRootList (TSequenceOf < TDirectory > & fillInRootList)

Interface Category:

API.

Purpose:

Copies the sequence of directories the locator uses by default into fillInRootList. The caller adopts the storage. GetDefaultRootList does not empty the fillInRootList argument first. The default roots are defined as part of the installation process, and minimally specify the single directory specified in the environment variable TaligentRoot is used.

Calling Context:

Call this function directly.

Parameters:

TSequenceOf < TDirectory > & fillInRootList -The sequence of directories to which is added the directories the locator uses by default.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMultipleRootLocator::RemoveDuplicateNames

static void RemoveDuplicateNames (TSequenceOf < TFileSystemEntity > &, bool andDelete =false)

Interface Category:

API.

Purpose:

Goes through the specified sequence and removes each entry whose name is the same as any previous entry. The "name" used for comparison is the string returned by TFileSystemEntity::GetName, which is to say, the "file name" part of the File system entity, exclusive of any directory or path components. Note: To get a list of matches sorted by something other than the search order, pass in a TSortedSequenceOf<TFileSystemEntity>, which was constructed with a comparator of your choice. Two comparators for TFileSystemEntities are provided: TMultipleRootLocator::TNewestFirst and TMultipleRootLocator::TOldestFirst.

Calling Context:

Call this function directly.

Parameters:

TSequenceOf < TFileSystemEntity > & -The sequence of File system entities from which to remove each entry whose name is the same as any previous entry.
bool andDelete =false -If true, delete each removed entity.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.