<?xml version="1.0" encoding="UTF-8"?> | |
<!-- | |
Licensed to the Apache Software Foundation (ASF) under one or more contributor | |
license agreements. See the NOTICE.txt file distributed with this work for | |
additional information regarding copyright ownership. The ASF licenses this | |
file to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 | |
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. | |
--> | |
<document> | |
<properties> | |
<title>Representation of Profiles</title> | |
<author email="Sean.Kelly@jpl.nasa.gov">Sean Kelly</author> | |
</properties> | |
<body> | |
<section name="Representation of Profiles"> | |
<p>Within the OODT Framework, profiles are represented as RDF | |
documents, XML documents, or Java objects. The Java Profile | |
class can yield itself as an RDF or XML document, and you can | |
construct a Java Profile from an XML document that describes a | |
profile. | |
</p> | |
</section> | |
<section name="Introduction"> | |
<p>No matter what their origin or whether they're to be short | |
lived, profiles have a physical representation at one time | |
within the OODT framework. Typically, you'll use the Java class | |
<code>Profile</code> when working with Java, or the | |
RDF or XML document version when working in other environments. | |
The RDF representation uses the RDF XML structure and RDF schema | |
to describe profiles. The XML document version uses an | |
OODT-specific XML vocabulary and DTD. | |
</p> | |
<p><em>For C/C++ Users:</em> There is not yet a C/C++ representation of a profile. | |
Use the RDF or XML representation. | |
</p> | |
<p><em>Note:</em>The RDF representation is currently a work-in-progress. | |
</p> | |
<p>If you're developing a new kind of profile server, you | |
should become familiar with the Java | |
<code>Profile</code> class. If you're searching for | |
profiles, you can just use the RDF or XML representations. | |
</p> | |
</section> | |
<section name="XML Profiles"> | |
<p>Profiles can be represented as XML documents that conform to | |
the OODT Profile Document Type Definition (DTD). The Formal | |
Public Identifier of the OODT Profile DTD is <code>-//JPL//DTD | |
Profile 1.0//EN</code>. The normative System Identifier is | |
<a>http://oodt.jpl.nasa.gov/grid-profile/dtd/prof.dtd</a>. | |
</p> | |
<p>Although you should refer to the normative System | |
Identifier for the latest reference version, see the following: | |
</p> | |
<source><![CDATA[<!ELEMENT profiles | |
(profile*)> | |
<!ELEMENT profile | |
(profAttributes, | |
resAttributes, | |
profElement*)> | |
<!ELEMENT profAttributes | |
(profId, profVersion?, profType, | |
profStatusId, profSecurityType?, profParentId?, profChildId*, | |
profRegAuthority?, profRevisionNote*)> | |
<!ELEMENT resAttributes | |
(Identifier, Title?, Format*, Description?, Creator*, Subject*, | |
Publisher*, Contributor*, Date*, Type*, Source*, | |
Language*, Relation*, Coverage*, Rights*, | |
resContext+, resAggregation?, resClass, resLocation*)> | |
<!ELEMENT profElement | |
(elemId?, elemName, elemDesc?, elemType?, elemUnit?, | |
elemEnumFlag, (elemValue* | (elemMinValue, elemMaxValue)), | |
elemSynonym*, | |
elemObligation?, elemMaxOccurrence?, elemComment?)> | |
<!ELEMENT profId (#PCDATA)> | |
<!ELEMENT profVersion (#PCDATA)> | |
<!ELEMENT profType (#PCDATA)> | |
<!ELEMENT profParentId (#PCDATA)> | |
<!ELEMENT profChildId (#PCDATA)> | |
<!ELEMENT profStatusId (#PCDATA)> | |
<!ELEMENT profSecurityType (#PCDATA)> | |
<!ELEMENT profRegAuthority (#PCDATA)> | |
<!ELEMENT profRevisionNote (#PCDATA)> | |
<!ELEMENT Identifier (#PCDATA)> | |
<!ELEMENT Title (#PCDATA)> | |
<!ELEMENT Format (#PCDATA)> | |
<!ELEMENT Description (#PCDATA)> | |
<!ELEMENT Creator (#PCDATA)> | |
<!ELEMENT Subject (#PCDATA)> | |
<!ELEMENT Publisher (#PCDATA)> | |
<!ELEMENT Contributor (#PCDATA)> | |
<!ELEMENT Date (#PCDATA)> | |
<!ELEMENT Type (#PCDATA)> | |
<!ELEMENT Source (#PCDATA)> | |
<!ELEMENT Language (#PCDATA)> | |
<!ELEMENT Relation (#PCDATA)> | |
<!ELEMENT Coverage (#PCDATA)> | |
<!ELEMENT Rights (#PCDATA)> | |
<!ELEMENT resContext (#PCDATA)> | |
<!ELEMENT resAggregation (#PCDATA)> | |
<!ELEMENT resClass (#PCDATA)> | |
<!ELEMENT resLocation (#PCDATA)> | |
<!ELEMENT elemId (#PCDATA)> | |
<!ELEMENT elemName (#PCDATA)> | |
<!ELEMENT elemType (#PCDATA)> | |
<!ELEMENT elemEnumFlag (#PCDATA)> | |
<!ELEMENT elemDesc (#PCDATA)> | |
<!ELEMENT elemSynonym (#PCDATA)> | |
<!ELEMENT elemUnit (#PCDATA)> | |
<!ELEMENT elemValue (#PCDATA)> | |
<!ELEMENT elemMinValue (#PCDATA)> | |
<!ELEMENT elemMaxValue (#PCDATA)> | |
<!ELEMENT elemObligation (#PCDATA)> | |
<!ELEMENT elemMaxOccurrence (#PCDATA)> | |
<!ELEMENT elemComment (#PCDATA)>]]></source> | |
<subsection name="Collections of Profiles"> | |
<p>As you can see from the above,an | |
XML element, <code>profiles</code> is a | |
container element to hold zero or more profiles. Use this | |
element where it's necessary to manipulate a collection of | |
profiles without regard to order. | |
</p> | |
</subsection> | |
</section> | |
<section name="Java Representation of Profiles"> | |
<p>The OODT source code includes a class | |
<code>jpl.eda.profile.Profile</code> for object | |
represenation of a profile. You can construct a | |
<code>Profile</code> object from an RDF or XML | |
document or create a blank one to populate with metadata | |
later. | |
</p> | |
<p>To construct a new, blank profile, use the no-arguments | |
constructor. To construct a profile from an RDF or XML | |
document, use the constructor accepting a Resource or a DOM | |
<code>Node</code>, respectively. The DOM node | |
should be a <code>Element</code> representing the | |
<code>profile</code> element. | |
Alternatively, if your XML document exists as a string, call | |
the constructor taking a single string. | |
</p> | |
<subsection name="Accessing Profile Metadata"> | |
<p>To access the metadata of a profile, call the methods to | |
retrieve the profile attributes, the resource attributes, or | |
the profile elements. | |
</p> | |
<subsection name="Accessing the Profile Attributes"> | |
<p>You retrieve the profile attributes by calling | |
<code>getProfileAttributes</code> on a | |
<code>Profile</code>. This returns an | |
<code>ProfileAttributes</code> object which provides | |
methods to get and set the various attributes. Setting a | |
value sets it for the <code>Profile</code> to which | |
the <code>ProfileAttributes</code> belongs. | |
</p> | |
<p>A value of <code>null</code> for an optional | |
attribute means the value isn't set. | |
</p> | |
</subsection> | |
<subsection name="Accessing the Resource Attributes"> | |
<p>You retrieve the resource attributes similarly as for | |
profile attributes, calling | |
<code>getResourceAttributes</code> to yield a | |
<code>ResourceAttributes</code> object. | |
</p> | |
<p>The <code>ResourceAttributes</code> has | |
methods to get and set various attributes. Note that many | |
of the attributes are multi-valued. For example, the | |
resource profiled will likely cover several subjects. In | |
this case, the "get" method, | |
<code>getSubjects</code>, returns a | |
<code>java.util.List</code> of | |
<code>String</code>s. There is no set method. | |
Instead, you just manipulate the list to add and remove | |
subjects. | |
</p> | |
<p><em>Note:</em> All of the "get" functions that return | |
<code>List</code>s return lists of | |
<code>String</code>s, except for | |
<code>getDates</code>, which returns a list of | |
<code>java.util.Date</code>s. | |
</p> | |
<p>For other attributes which are singly valued, there is | |
both a set and get method. For optional values, a value of | |
<code>null</code> means the attribute isn't set. | |
</p> | |
</subsection> | |
<subsection name="Accessing the Profile Elements"> | |
<p>The profile stores its profile elements in a | |
<code>java.util.Map</code>, mapping the name of | |
the profile element (as a <code>String</code>) to | |
an object of class <code>ProfileElement</code>. | |
To access this map, call the method | |
<code>getProfileElements</code> on a | |
<code>Profile</code>. Because this method returns | |
a reference to the <code>Profile</code>'s map, any | |
updates to the map affect the profile immediately. | |
</p> | |
<p><em>Caution:</em> Never store anything but | |
<code>String</code>s as keys and | |
<code>ProfileElement</code>s (or objects of its | |
subclasses) as values in a profile element map. The | |
software will not operate correctly if any other kind of | |
object is stored. | |
</p> | |
<subsection name="Common Attributes of Profile Elements"> | |
<p>The class | |
<code>jpl.eda.profile.ProfileElement</code> | |
contains the common parts of every profile element, such | |
as its required name, its optional description, and so | |
forth. Use the value <code>null</code> for any | |
optional attribute that's unset. | |
</p> | |
<p>The <code>ProfileElement</code> stores its | |
synonyms as a <code>java.util.List</code> of | |
<code>String</code>s. Manipulate the list | |
directly to add or remove synonyms. | |
</p> | |
<p>The <code>ProfileElement</code> class is | |
abstract. To create new profile elements for a profile, | |
you need to create objects of one of the concrete | |
<code>ProfileElement</code> subclasses: | |
</p> | |
<ul> | |
<li><code>EnumeratedProfileElement</code></li> | |
<li><code>RangedProfileElement</code></li> | |
<li><code>UnspecifiedProfileElement</code></li> | |
</ul> | |
<p>The following sections detail each kind of profile | |
element. | |
</p> | |
</subsection> | |
<subsection name="Elements with Enumerated Values"> | |
<p>For profile elements that maintain a specified list of | |
valid values, use the | |
<code>EnumeratedProfileElement</code> class. | |
Objects of this class maintian a | |
<code>java.util.List</code> of values. You can | |
pass in a list of values when constrcuting the object, or | |
can call the <code>getValues</code> method and | |
manipulate the list directly. | |
</p> | |
<p>Queries that arrive for an enumerated profile | |
element must match one of the listed elements exactly | |
unless it's a negative (not-equal-to) query. For | |
example, suppose we had an enumerated profile element | |
<code>filter</code> with values | |
<code>infrared</code>, <code>visible</code>, | |
and <code>ultraviolet</code>. A query asking for | |
a filter equal to infrared should match, as well as a | |
query asking for a filter greater than or equal to | |
infrared. A query asking for a filter not equal to | |
infrared shouldn't match, while a query asking for a | |
filter not equal to x-ray should match. | |
</p> | |
</subsection> | |
<subsection name="Elements with a Range of Values"> | |
<p>You can represent profile elements that have a range | |
of valid values with the | |
<code>RangedProfileElement</code> class. | |
Construct this class with the minimum and maximum values, | |
which must be numeric. | |
</p> | |
<p>Use the <code>getMinValue</code> to get the | |
minimum value and <code>getMaxValue</code> to | |
get the maximum value. | |
</p> | |
<p>Querying a profile that uses a range of values | |
considers the range as inclusive. For example, suppose | |
the ranged profile element | |
<code>temperature</code> has a minimum value of 32 | |
and a maximum value of 212. A query that requests | |
temperatures less than 32 shouldn't match, but less than or | |
equal to 32 should match. | |
</p> | |
</subsection> | |
<subsection name="Elements with no Specified Values"> | |
<p>For profile elements that you always want to match a | |
query without explicitly listing each valid value or a | |
range of legal numeric values you can use the class | |
<code>UnspecifiedProfileElement</code>. This | |
class identifies an element with no range or list of | |
valid values. | |
</p> | |
<p>Queries that arrive at such an element will | |
<span class="emphasis"><em>always</em></span> match, even if they're | |
negative (not-equal-to) queries. | |
</p> | |
</subsection> | |
</subsection> | |
</subsection> | |
</section> | |
</body> | |
</document> |