The find operation finds elements that correspond to a particular query.

The find operation obtains objects of any type by searching for a particular name. The query results are provided in the form of a QueryResult object, which contains an array of FinderResult objects with a total counter. The query itself is passed to find as the second parameter, as the following operation declaration shows.

public QueryResult find(String type, String query, String username, String password);

The plug-in that contains the objects that you are looking for parses the query. The plug-in defines the query language that the find operation uses. Consequently, the syntax of the query parameter differs according to the implementation of the plug-in. Most of the officially supported Orchestrator plug-ins do not store any objects in the inventory, so they do not expose anything that can be searched for.

The following table describes the find operation query parameter syntax and behavior for each of the supported Orchestrator plug-ins.

Table 1. Query Syntax of the Orchestrator Plug-Ins

Orchestrator Plug-In

Query Parameter Syntax

Query Behavior

Database, for example Lifecycle Manager

String

Searches for object names in SQL database tables. Orchestrator sets the search string in a SQL WHERE keyword search. It searches the primary keys, then the object IDs in the database.

Enumeration

Not applicable

Stores nothing in the inventory. You can find enumerations on each data type that contains enumeration types.

Jakarta common set

Not applicable

Stores nothing in the inventory.

JDBC

Not applicable

Stores nothing in the inventory.

Library

Not applicable

Stores nothing in the inventory.

Mail

Not applicable

Stores nothing in the inventory.

SSH

If you have configured Orchestrator to use SSH connections, you can make queries SSH commands.

Stores nothing in the inventory.

vCenter Server

String or null

Ignores the query string and returns all objects of the specified type.

XML

Not applicable

Stores nothing in the inventory.

When you develop plug-ins, you can define a query language to use find to search for named objects through the custom plug-in. This definition is not mandatory. The syntax of the query parameter is entirely dependent on the query language that the plug-in implements. To avoid defining a query language, make find return all objects, as in the case of the VMware Infrastructure plug-ins.

The size of the array of objects that the QueryResult returns depends on the definition of the plug-in through which you make the query. For the queries you make through the standard Orchestrator plug-ins, the array contains an unlimited number of FinderResult objects. Developers of third-party plug-ins, however, can set a limit on the number of results that the query returns. If the value of totalCount exceeds the number of objects in the array of FinderResult objects, the array does not include all of the objects found in the queried inventory. The totalCount property does report the total number of FinderResult objects found. The totalCount property can be negative, which signifies that the plug-in cannot determine how many corresponding objects are in the plug-in.

Type

Value

Description

String

type

Type of object looked for.

String

query

The query.

The query is a string enclosed in quotation marks. Any object of the type specified by the type parameter with a name that matches the query string is returned in the QueryResult object.

String

username

Orchestrator user name.

String

password

Orchestrator password.

Return Value

Returns the result of the query as a QueryResult object.

If find fails to match an object, QueryResult.getTotalCount returns 0 and QueryResult.getElement returns null.

If the server does not recognize the object type or plug-in searched for, find throws an exception. The find operation also returns an exception if you pass it an invalid parameter.