Server Object Search

From Multiverse

Multiverse Servers

Installing  •  Installing on Linux  •  Running  •  Troubleshooting  •  FAQ  •  Release Notes  •  Updating  •  JMX Monitoring & Mgmt.

Infrastructure

Platform Architecture  •  Registering a World  •  Proxy Server  •  Event Handling  •  World Manager  •  Voice Server

Messaging System

Perception Messaging  •  Using Extension Messages  •  Message Marshalling  •  Multi-subject Messaging  •  Message Catalog

Object Architecture

World Instancing  •  Server Object Search  •  Server Regions  •  Server Markers

Scalability and Performance

Overview  •  Scalability Testing

Reference

File Layout  •  Property File  •  Logging  •  API

Contents 1 Overview 1.1 Object collections 1.2 Search criteria 1.3 Search selection 2 Example 3 Implementing searchable collections 4 EntitySearchable

Overview

Use the server object search framework to search for instances, markers, and regions based on arbitrary criteria.

Object collections

The server provides APIs that enable you to search for:

• Instances: Find all loaded Instance objects. You can search instances by property values and select the properties that are returned.
• Markers: Find all Marker objects inside a given instance. You can search markers by property values inside a single instance and get Marker objects with information selected by several flags.
• Regions: Find all Region objects inside a given instance. You can search regions by property values inside a single instance and get Region objects with information selected by several flags.

Each of these object has an OBJECT_TYPE member property of type ObjectType.

Search criteria

Each type of object collection defines its own search criteria. Define search criteria through the three classes that implement the SearchClause interface:

• Marker.Search - defines a search clause for markers.
• Region.Search - defines a search clause for regions.
• PropertySearch - a generic implementation of SearchClause.

To add additional search criteria, create a sub-class of PropertySearch.

Search selection

The SearchSelection controls what information is returned from each object matching the search criteria. Information is selected using bit-flags or property names. The supported bit-flags and properties are defined by each searchable collection. All the properties can be fetched by setting a single flag.

The search result is typically a collection of objects. Two formatting options are available:

• SearchSelection.RESULT_KEYED -- Result is a collection of SearchEntry objects containing the object key and object value.
• SearchSelection.RESULT_KEY_ONLY -- Result is a collection of object keys or names.

How these options are supported, if at all, is defined by each searchable collection.

Example

Example of searching for instances, demonstrating the three result options.

queryProps = HashMap()
# Add matching properties to queryProps
search = PropertySearch(queryProps)

# Get the instance name and instance template name
selection = SearchSelection()
selection.addProperty(InstanceClient.TEMPL_INSTANCE_NAME)
selection.addProperty(InstanceClient.TEMPL_INSTANCE_TEMPLATE_NAME)

# Search using the default format
instances = SearchManager.searchObjects(ObjectTypes.instance, search, selection)
print "1: " + str(instances)

# Get collection of SearchEntry
selection.setResultOption(SearchSelection.RESULT_KEYED)
instances = SearchManager.searchObjects(ObjectTypes.instance, search, selection)
print "2: " + str(instances)

# Get collection of instance oids
selection.setResultOption(SearchSelection.RESULT_KEY_ONLY)
instances = SearchManager.searchObjects(ObjectTypes.instance, search, selection)
print "3: " + str(instances)

Example of searching for markers.

# Get the instance oid
instanceOid = InstanceClient.getInstanceOid("default")

# Define the search criteria
queryProps = HashMap()
queryProps.put("Property1","value1")
search = Marker.Search(instanceOid,queryProps)

# Search and return all marker info
selection = SearchSelection(Marker.PROP_ALL)
markers = SearchManager.searchObjects(Marker.OBJECT_TYPE, search, selection)
print "1: " + str(markers)

# Search and return SearchEntry objects
selection = SearchSelection(Marker.PROP_ALL,SearchSelection.RESULT_KEYED)
markers = SearchManager.searchObjects(Marker.OBJECT_TYPE, search, selection)
print "2: " + str(markers)

Implementing searchable collections

Any object is searchable.

1. Implement search criteria:
   • PropertySearch
   • Matchers
2. Define selectable attributes:
   • Flags vs. properties
   • Result options: KEYED, KEY_ONLY
3. Implement the Searchable interface.
   • Implement the runSearch() method.
   • Delegate to another collection.

EntitySearchable

The EntitySearchable class provides a generic searchable collection for registered entities. It supports PropertySearch matches against registered entities of a given ObjectType. It searches the entity properties and returns selected property values. The object key is the entity OID. It supports selection options RESULT_KEYED and RESULT_KEY_ONLY.