Copyright 2007 The Trustees of Indiana University Licensed under an Apache-style license (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.cs.indiana.edu/dde/LICENSE-myLEAD Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Author: Scott Jensen, scjensen@cs.indiana.edu Version 1.0.8 The stats available regarding the service may grow or change over time. To avoid changes to the schema. each statistic regarding the catalog service is returned as a catalogStat element. The fields in the user definition are based on the FGDC schema's Contact schema definition. This filter is used to determine what objects other than the target should be included in the result. If neither the parentFilter or the childFilter is included, then this is the same as the TARGET hierarchy filter. If either the parent or child filter has a distance limit of 0, then all of the parents or children respectively are included. If parents or children should be excluded by type, then each type to be excluded should be an excluded element in the respective filter. The value type can be used to query for any metadata element that is numeric(int or float) , date, time, or datetime. The range parameters are strings and are converted in the server to the appropriate data type based on the definition for the specified metadata element. The range type can be used to query for any metadata element that is numeric(int or float) , date, time, or datetime. The range parameters are strings and are converted in the server to the appropriate data type based on the definition for the specified metadata element. This type is used to provide queries with the ability to check the relationship of a spatial metadata element with a single x,y coordinate. The only valid comparisons for a point are whether the spatial element is equal to or contains that point. The spatial comparison type also allows for within and intersects. For point comparisons, within is the same as equals and intersects is the same as contains. The polygon spatial type must consist of at least four points, and the first and last point must be the same coordinate. Metadata is stored in the catalog as metadata properties which in turn contain metadata elements. The actual metadata values are stored in the metadata elements. The query element types are not based strictly on data types, but also what type of relation the user is looking for. For text elements the user is looking for exact matches, contains, or possibly starts with. For numeric or date elements the user is either comparing to a single value (greater, lesser, equal) or is looking within a range. All numeric date, and time elements can be specified using value or range query elements. The element definition in the catalog knows if the value should be an int, float (double), date, time, or datetime element. The point and polygon query elements are used to specify spacial queries. If no comparison is specified, then checks only for existence of the element, not the value. The optional parameterize and description attributes only apply when the query being constructed is saved. The parameterize atttribute allows the user to specify if the value specified as the criteria should be saved in the definition or whether this should be made a parameter the user, or another user for public template queries, would need to fill in each time. If true, then this is treated as a parameter in the saved definition. The description element allows the user to add annotatins as to the purpose of the element in the query. Generally it will probably be obvious as to why an element is in a query, but particularly for public queries, this allows annotations as to how the element should be used. Within a metadata property criteria in a query, a user can specify criteria for metadata elements within that property. This type allows a user to specify that if any of the AND sets or queryElement criteria within this OR set match, then that metadata property matches this criteria. This is NOT an exclusive OR. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. Within a metadata property criteria in a query, a user can specify criteria for metadata elements within that property. This type allows a user to specify that if ALL of the OR sets and queryElement criteria within this AND set must match for a metadata property to match this criteria. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. Metadata is stored in the catalog as metadata properties which in turn contain metadata elements and possibly nested metadata properties know as sub-properties. The actual metadata values are stored in the metadata elements. The metadata properties are used to provide structure so complex concepts can be modeled as metadata properties. The query criteria for a metadata property can contain zero or more element criteria. These can be multiple instances of queryElement or queryElementOrSet, and there is an implicit AND of these instances. The same appraoch is used for queryPropertyOrSet and queryProperty. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. This type can be included in an object or as a sub-property of another property. The OR type can contain any number of queryProperty or a queryPropertyAndSet of properties. In a query, if any of the properties or AND sets match for an object, then this OR set will be considered a match. It is NOT an exclusive OR. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. This type can be included in an object or as a sub-property of another property. The AND type can contain any number of queryProperty or a queryPropertyOrSet of properties. In a query, ALL of the properties and OR sets must match for an object to be considered a match for this AND set. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. Each catalog query has a particular target - such as a file or collection that a user is searching for. The target may also need to contained in and/or contain a hierarchy of collections or files. The target may also have specific properties, or possibly just a type The queryObjectType is used both for targets and is extended for objects used to define the context of the target in a query. There is an implicit AND of the queryProperty and queryPropertyOrSet included in an object. The optional description attribute is only applicable when a query definition is being saved - see discussion in queryElementType. Queries consist of a target and optionally a context for the query The context consists of other objects (collections and files) that the target either contains or is contained within. The objects used to specify the query context are similar to the target, but also need to specify relationships (parent or child) and contain additional hierarchy. This type is used for the objects in the query context and it extends the type used for the target. The queryOrSet and context instances are an implicit AND. If the context should be an OR, then the context should start with a single queryOrSet. This set is a disjunctive "OR" of two or more components or nested AND types. A disjunctive (OR) set cannot be nested here. This set is a conjunctive "AND" of two or more components or nested OR types. A conjunctive (AND) set cannot be nested here. The context query determines the context of the target and starts with one or more queryOrSets and/or queryComponents. Each component specifies its relationship to the target. There is an implicit AND of the sets and components in the context. The result format specifies filters used to format the content of the query result as well as the delivery method. The hierarchy filters determine what objects in addition to the objects matching the target should be returned. For example, if the query targets collections containing certain files as the context, they may want the result to be those collections and their parent experiment. The content filters determine the extent of the metadata returned for each object in the result. the property exclusion allows the user to filter out certain properties to be excluded from the result. The object set type is used to return a set of instances of schema-valid instances as defined by the members of the catalog object group. The objects must indicate their relationships within the object instances themselves if the parent - child relationships are relevant. All of the query response object types based on one or more element filters use this type. This is a name/value pair with the value as a simple type and the name as an XML attribute. Each object included in a query response based on element filters is encapsulated in an instance of this type. The globally unique ID of the object is a required attribute for response elements of this type. Each element included in the filter is an instance of the metadataElement. If this object has any child objects (e.g., an experiment containing files) then those children can be nested as instance of the elementResponse element. A query response can be empty, so the minOccurs for all response types is set to zero. Although not enforced by the schema, all objects in a response will use the same hierarchy filter, so if the SUBTREE filter is specified in the query, then the full subtree will be included for all objects in the query response. Each of the query methods can return either directly in the response or indirectly by returning a URL which can then be accessed as a stream. The choice between these two options is contained in this element. The context query, query by ID, and workspace query all use the query response element. If the results are passed back as a stream, the contents at the URL is the queryResponseSet that would have been passed if the direct method had been used. The metadata stored in the catalog is divided into broad categories, and then metadata properties are defined for each category. The metadata properties all have a name and source of the definition (defines what the name means). Each metadata property also has a human readable description and short description. Metadata elements are then defined within each property and the values are stored as elements in the catalog. A category can have multiple properties and a property can contain multiple metadata elements. This operation is used to get the global ID and description of every public template query and every query defined by the user making the request. This response provides the global ID and description of every public template query definition (which is available to any user) and those query definitions previouly saved by the user who made the request. The public and private query definitions are returned as separate elements. If there are no public templates and the user has not saved any query definitions, the queryDescriptionSet or resultStreamUrl will be excluded. This method is called to get the definition for a specific existing query that is either a public template query available to all users, or a query definition owned by the user making the request. This response returns the target and context component of the query specified in the request. Since queries are not required to have a context, the context component is optional. If the query ID specified in the request is not valid or not available to the user making the request, this will be reflected in the status and the choice for the queryDefinition element or the resultStreamUrl will be excluded. This method can be called with a query definition to be saved in the metadata catalog so it can be reused. The public attribute allows the user to specify if the query definition should be saved as a public query template available to other users. This method can be called to delete a saved query definition that is private to the user making the request.