Registry Query Beans

Especially for remote access, 
* There exists no programmatic way to query for entitlement data in the registry.
* There exists no programmatic way to query for group data in the registry.
* There exists no programmatic way to query for people data in the registry.
* There exists no programmatic way to query for service data in the registry.
* There exists no programmatic way to query for an arbitrary data object in the registry.

• All Query types
  1. Ability to search on any combination of the supported query fields, both
     • exact match fields, and
     • fields that support wildcard searching.
  2. Return the search results as a collection of Registry Entities, which are Java Persistence Entities.
  3. All queries should leverage Java Persistence Query Language (EJBQL) using Java Persistence Entities, not SQL using JDBC.
• Entitlement Query
  1. Ability to query by an exact match of the following fields, at a minimum:
     • Registry UID
     • Entitled Person UID
     • Sponsoring Person UID
     • Owning Service identifier string (UUSID)
  2. Ability to query by either an exact match or a substring (wildcard) match on the following fields, at a minimum:
     • Entitlement data
  3. Ability to return a record snapshot in DSML format given a service
     • UID
• Group Query
  1. Ability to query by an exact match of the following fields, at a minimum:
     • Registry UID
     • Person Administrator Auth ID
     • Service Administrator identifier string (UUSID)
     • Person Manager Auth ID
     • Service Manager identifier string (UUSID)
     • Contact Person Auth ID
     • Member Person Auth ID
  2. Ability to query by either an exact match or a substring (wildcard) match on the following fields, at a minimum:
     • Group identifier string (UUGID)
  3. Ability to return a record snapshot in DSML format given a group
     • UID, or
     • UUGID
  4. Ability to retrieve group members given a UUGID
• Person Query
  1. Ability to query by an exact match of the following fields, at a minimum:
     • Virginia Tech ID Number
     • Virginia Tech Banner PIDM
     • Registry UID
  2. Ability to query by either an exact match or a substring (wildcard) match on the following fields, at a minimum:
     • First Name (not just preferred names)
     • Last Name (not just preferred names)
     • Phone Number
     • PID
     • Guest ID
     • Email address including forwards, aliases and administratively defined addresses
  3. Ability to return a record snapshot (full or specified attribute only) in DSML format given a person
     • UID, or
     • PID
• Service Query
  1. Ability to query by an exact match of the following fields, at a minimum:
     • Registry UID
     • Person Administrator Auth ID
     • Contact Person Auth ID
     • Attributes service may view
  2. Ability to query by either an exact match or a substring (wildcard) match on the following fields, at a minimum:
     • Service identifier string (UUSID)
  3. Ability to return a record snapshot in DSML format given a service
     • UID, or
     • UUSID
• Generic Query
  1. Ability to do adhoc queries on an arbitrary Registry Entity.

1. Must be implemented as clustered stateless session beans.
2. As needed, expose query method(s) via a web service.

Functionality to query the Registry using session beans is provided both for the specific data objects:

• Entitlements
• Groups
• Persons
• Services

and for abitrary data objects. Both types of query functionality provide at least one query search that is very flexible in terms of specifying the parameter(s) for the the search. These flexible searches are implemented using a SearchCriteria from the ed package to provide the search parameters. Each data object for which a specific query session bean is provided has a corresponding specific SearchCriteria:

• EntitlementSearchCriteria
• GroupSearchCriteria
• PersonSearchCriteria
• ServiceSearchCriteria

The query session bean for searching an arbitrary data object uses the generic DirectSearchCriteria. This DirectSearchCriteria can also be used with any of the data-object specific query session beans. All of the SearchCriteria allow limitations to be imposed on the search, including

• maximum number of results to be returned,
• starting result number for the search, which can be used in conjunction with the maximum number of results to retrieve results in batches, and
• entity lazy loading requirement.

Note that specifying the need to load all data object fields (the lazy loading requirement) can increase the time the search takes significantly.

The easiest to use searching involves the use of the session bean and its corresponding SearchCriteria for one of the specific data object beans. The steps to perform this type of search are:

1. Instantiate a new data-object specific SearchCriteria.
2. Call the needed setter method(s) in this SearchCriteria to provide the search data.
3. Call the session bean search method that accepts the data-object specific SearchCriteria.

A setter method is provided for each supported query field. If the query field allows wildcard searching, the wildcard(s) are included using an *. The search method handles all the details for building the EJBQL query from the supplied parameter values, including use of the wildcard characters, executing the search, and returning the collection of search results. The client requesting the search does not have to know anything about:

• the Registry entities needed for the search
• how these Registry entities needed to be joined
• how to build an EJBQL involving wildcard searching
• etc.

Example - retrieve all people with last name smith whose first name starts with a:

  final PersonSearchCriteria psc = new PersonSearchCriteria();
  psc.setFirstName("A*");
  psc.setLastName("Smith");
  List<Person> results = personQuery.searchPeople(psc);

Searching using the query session bean for an arbitrary data object allows searching of Registry entities for which a specific query session bean is not available, as well as searching of fields for which setter methods are not supported as query fields in the data-object specific query session beans. The client requesting the search is responsible for providing all the details for the search, including:

• the EJBQL for the search, and
• the parameters for the search (field name plus value).

This can be quite simple:

  final DirectSearchCriteria criteria = new DirectSearchCriteria();
  criteria.setEjbQL("SELECT t FROM Ticket t WHERE t.uuid = :uuid");
  criteria.setParameter("uuid", "ticketid");
  final List<Ticket> tickets = query.search(Ticket.class, criteria);

However if the query needs to join multiple Registry entities, include wildcard searching, etc. the client must know how to specify all of that in the EJBQL passed to the setEjbQL method.

The data-object specific query session beans provide additional searches that do not make use of the SearchCriteria. For example, search method(s) are provided to retrieve an entity using an exact match on a single field to return the record snapshot in DSML format. Typically the exact match is peformed using the Registry UID or the entity identifier string. Sometimes additional searches are implemented that return something other than the entity data itself, such as the group method to retrieve group members.

• Registry Query Javadocs
• Registry Core Javadocs

• Functional Requirement 7 means we will need 256 (2⁸) finders for all the combinations of searchable fields. Need to dig into EJBQL to see if there are any shortcuts that can be taken to decrease the number of finders. — dhawes@vt.edu 2005/04/19 19:40
  • JBoss Dynamic QL is the answer to this. It will allow us to dynamically create a finder. — dhawes@vt.edu 2005/04/22 12:24
• java.util.Date should not be used in any web service classes, apparently it is not mapped.
  • java.util.Calendar should be used instead. See http://java.sun.com/webservices/docs/1.5/tutorial/doc/JAXBWorks5.html#wp82947 — dfisher@vt.edu 2005/05/02 15:38