Added: oodt/trunk/profile/src/site/xdoc/info/index.xml
URL:
http://svn.apache.org/viewvc/oodt/trunk/profile/src/site/xdoc/info/index.xml?rev=1079088&view=auto
==============================================================================
--- oodt/trunk/profile/src/site/xdoc/info/index.xml (added)
+++ oodt/trunk/profile/src/site/xdoc/info/index.xml Tue Mar 8 02:13:07 2011
@@ -0,0 +1,848 @@
+<?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>Information Captured in a Profile</title>
+ <author email="[email protected]">Sean Kelly</author>
+ </properties>
+ <!-- Infected Mushroom - Deeply Disturbed -->
+ <body>
+ <section name="Information Captured in a Profile">
+
+ <p>A profile serves as a generic template for describing the
+ characteristics of a resource. The question posed to a profile
+ generally takes the form of, "Can you answer <var>X</var>?" or
+ "Do you know the location of <var>X</var>?" where <var>X</var>
+ is some resource being sought. The more fully a profile describes
+ a particular resource, the better the profile can be used to
+ determine if the resource has the information in <var>X</var>.
+ </p>
+
+ </section>
+
+ <section name="Information and Organization">
+ <p>Profile servers capture three kinds of information:</p>
+
+ <ul>
+ <li><b>Resource Attributes</b> <p>Resource attributes are
+ metadata about the resource's <em>inception</em>. These
+ attributes include the creator of the resource, in what
+ language it exists, when it was created, and so forth.
+ These attributes are based on the work of the <a
+ href="http://www.dmci.org/";>Dublin Core Metadata Initiative</a>.
+ </p>
+ </li>
+
+ <li><b>Profile Elements</b> <p>Profile elements are metadata
+ about the resource's <em>composition</em>. These tell you
+ about the morphology of the resource, such as data types
+ captured within in, minimum and maximum values, synonymous
+ elements, and so forth. These attributes are based on <a
+ href="http://metadata-standards.org/11179/";>ISO/IEC 11179
+ standards</a>.
+ </p>
+ </li>
+
+ <li><b>Profile Attributes</b> <p>Profile attributes are
+ metadata about the <em>profile itself</em>, such as who
+ made it, whether it's classified, revision notes, and so
+ forth. It also has a unique identifying <a
+ href="http://www.alvestrand.no/objectid/index.html";>Object
+ Identifier (OID)</a>.
+ </p>
+ </li>
+ </ul>
+
+ <p>The following class diagram shows the relationship between
+ the different parts of a profile:
+ </p>
+
+ <img src="../images/class.png" alt="Class diagram"/>
+
+ <p>While this diagram shows the Java field names and Java
+ classes, the relationship applies to profiles whether they
+ exist as Java objects, as RDF documents, or as XML documents
+ in the profile vocabulary.
+ </p>
+ </section>
+
+ <section name="Inception Metadata">
+ <p>Profiles, whether expressed in RDF or in their own XML
+ vocabulary, have a section for capturing information about the
+ resource's inception. This includes information about when the
+ resource was created, who created it, in what language it
+ exists, and so forth. Profiles use the element set recommended
+ by the Dublin Core Metadata Initiative (DCMI) set in order to
+ describe the inception of a resource, with some extensions.
+ </p>
+
+ <p>Collectively, these metadata are called the <i>resource
+ attributes</i> or <code>resAttributes</code> of the profile.
+ Every profile has one and only one set of
+ <code>resAttributes</code>. The metadata elements within the
+ <code>resAttributes</code> are defined in this section.
+ </p>
+
+ <subsection name="Identifier">
+ <p>As defined by the DCMI, the <code>Identifier</code> of a
+ resource is some unambiguous way to identify the resource.
+ In the profile implementation, one and only one
+ <code>Identifier</code> is <span
+ class="emphasis"><em>required</em></span>.
+ </p>
+
+ <p>It's highly recommended that <code>Identifier</code>s and
+ <code>resLocation</code>s (see below) be URIs, but there's
+ no software enforcment for this <em>unless you convert a
+ Java profile to RDF</em> with the <code>toRDF</code> method.
+ Identifiers should be more like URNs, while resLocations
+ should be more like URLs.
+ </p>
+ </subsection>
+ <subsection name="Title">
+ <p>The <code>Title</code> names the resource, and is the name by
+ which the resource is formally known. The <code>Title</code> is
+ optional; if present, it may occur only once in a profile.
+ </p>
+ </subsection>
+ <subsection name="Format">
+ <p>The <code>Format</code> indicates the manifestation of the
+ resource. You can specify any number of <code>Format</code>s in
+ a profile.
+ </p>
+ </subsection>
+ <subsection name="Description">
+ <p>The <code>Description</code> element contains a free text
+ account of the content of the resource. It's optional in a
+ profile; if present, it may occur only once.
+ </p>
+ </subsection>
+ <subsection name="Creator">
+ <p>Zero or more <code>Creator</code>s may be specified in a
+ profile. <code>Creator</code>s contain the name of people or
+ organizations that created the resource.
+ </p>
+ </subsection>
+ <subsection name="Subject">
+ <p>You can list zero or more <code>Subject</code>s in a profile.
+ The purpose of the <code>Subject</code> elements is to contain a
+ keywords that describe the resource, usually selected from a
+ controlled vocabulary.
+ </p>
+ </subsection>
+ <subsection name="Publisher">
+ <p>Any number of <code>Publisher</code> elements may appear in a
+ profile. They contain the organization responsible for
+ making the resource available.
+ </p>
+ </subsection>
+ <subsection name="Contributor">
+ <p>A <code>Contributor</code> is a person or organization
+ providing auxilliary work towards the resource's creation.
+ Any number of <code>Contributor</code>s may be listed in a
+ profile.
+ </p>
+ </subsection>
+ <subsection name="Date">
+ <p><code>Date</code> elements indicate the times in history when
+ the resource was created. You can include any number of
+ <code>Date</code>s in a profile, although typically you'll
+ specify just one if you speciy any at all.
+ </p>
+ </subsection>
+ <subsection name="Type">
+ <p>The <code>Type</code> element indicates the nature of the
+ content of the resource, such as "fiction" for a work of
+ fiction or "image" for a dataset rendered graphically. You
+ can include any number of <code>Type</code>s in a profile.
+ </p>
+ </subsection>
+ <subsection name="Source">
+ <p>When a resource is derived others, the <code>Source</code>
+ element should indicate the <code>Identifier</code>s of the
+ referenced resources. You can specify any number of
+ <code>Source</code>s in a profile.
+ </p>
+ </subsection>
+ <subsection name="Language">
+ <p>For resources that contain natural language content, the
+ <code>Language</code> element indicates the languages in use.
+ You can specify this element any number of times in a
+ profile.
+ </p>
+ </subsection>
+ <subsection name="Relation">
+ <p>When a resource is related to others, you can specify the
+ <code>Identifier</code>s of the related resources using zero or
+ more <code>Relation</code> elements.
+ </p>
+ </subsection>
+ <subsection name="Coverage">
+ <p>For resources that cover a space or time or jurisdiction,
+ use the <code>Coverage</code> element to indicate such coverage.
+ This element may be listed any number of times in a profile,
+ and its content should come from a controlled vocabulary.
+ For resources with specific coordinate systems, it's better
+ to use profile elements, described below.
+ </p>
+ </subsection>
+ <subsection name="Rights">
+ <p>Copyright, ownership, redistribution, use, and other legal
+ issues may exist for a resource. When that happens, use the
+ <code>Rights</code> element to list the rights management
+ information. You can list zero or more <code>Rights</code>
+ elements in a profile.
+ </p>
+ <p><em>Note:</em> The official name of element for is plural
+ <code>Rights</code>; this is inconsistent with the other
+ metadata elements, but is consistent with the DCMI.
+ </p>
+ </subsection>
+ <subsection name="resContext">
+ <p>The <code>resContext</code> element identifies the application
+ environment or discipline within which the resource
+ originates and is derived from a taxonomy of scientific
+ disciplines. This element is required in a profile and may
+ occur multiple times.
+ </p>
+
+ <p>As an example, a <code>resContext</code> of
+ <code>NASA.PDS.Geoscience</code> tells that the resource is
+ associated with the Geoscience node of the Planetary Data
+ System.
+ </p>
+ </subsection>
+ <subsection name="resAggregation">
+ <p>The <code>resAggregation</code> element indicates the
+ aggregative structure of the resource. It tells you what
+ you'll get if you retrieve the resource: a granule, a
+ dataset, or a collection of datasets. The legal values of
+ this optional elements are:
+ </p>
+
+ <ul>
+ <li><code>granule</code>, meaning the resource is a single
+ product
+ </li>
+ <li><code>dataSet</code>, meaning the resource is a set of
+ products
+ </li>
+
+ <li><code>dataSetCollection</code>, meaning the resource is
+ collection of datasets
+ </li>
+ </ul>
+
+ <p>The <code>resAggregation</code> element is optional; however,
+ if specified, it may appear in a profile only once.
+ </p>
+ </subsection>
+ <subsection name="resClass">
+ <p>The <code>resClass</code> element identifies the kind of the
+ resource within a taxonomy of resource types. It's a
+ <em>required</em> element that is used by the OODT Framework
+ to determine how to treat the profile as well as the
+ resource named by the profile.
+ </p>
+
+ <p>For example, a <code>resClass</code> of
+ <code>system.productServer</code> indicates that the resource is
+ an OODT product server. A query that matches this profile
+ means that if the same query were given to the identified
+ product server, it would yield a result. A
+ <code>resClass</code> of <code>system.profileServer</code> means the
+ resource is a profile server. That means that while the
+ current profile server may or may not provide a matching
+ profile, another profile server might, forming an implicit
+ digraph of profile servers. Other valid <code>resClass</code>
+ values include <code>data.granule</code>, <code>data.dataSet</code>,
+ and <code>application.interface</code>.
+ </p>
+ </subsection>
+
+ <subsection name="resLocation">
+ <p>Zero or more <code>resLocation</code> elements may appear in
+ a profile. They tell where the resource is located, easily
+ the most important part of the profile. Because this
+ element may appear several times, all locations should be
+ considered valid; the application may pick the one that's
+ most convenient. The <code>resLocation</code> may also appear zero
+ times. This means that the profile indicates solely that
+ the resource existswhere is unknown.
+ </p>
+
+ <p>The interpretation of the resLocation is as a URI. For
+ example, a <code>resClass</code> of
+ <code>system.productServer</code> or
+ <code>system.profileServer</code> means that the
+ <code>resLocation</code> indicates an URN to a software object
+ name. Querying that object will yield either the desired
+ result (for product servers) or more matching profiles (for
+ profile servers). For a resClass of <code>data.granule</code>
+ or <code>data.dataSet</code>, the <code>resLocation</code> is an URL
+ to the granule or dataset.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Composition Metadata">
+ <p>The most interesting part of a profile is in the metadata
+ that describes the composition of the resource that the
+ profile profiles. The composition metadata is what enables a
+ profile server to tell if a particular resource can answer a
+ query.
+ </p>
+
+ <p>The composition metadata is based on the data element
+ description standards in ISO/IEC standard 11179. They are the
+ <i>profile elements</i> or <code>profElement</code>s of a profile.
+ Every profile may have zero or more <code>profElement</code>s, the
+ components of which are discussed in this section.
+ </p>
+
+ <subsection name="elemId">
+ <p>The <code>elemId</code> is an optional universally unique
+ identifier applied to the element.
+ </p>
+ </subsection>
+ <subsection name="elemName">
+ <p>The <code>elemName</code> is the <em>required</em> name of the
+ profile element. It serves as the title role of one of the
+ components of the resource.
+ </p>
+ </subsection>
+ <subsection name="elemDesc">
+ <p>The <code>elemDesc</code> is the description of the profile
+ element. Although the title may often be enough to identify
+ the purpose of the profile element, the description should
+ be used to provide any further, free-text information that
+ may be of importance to analysts and profile administrators.
+ The description is optional.
+ </p>
+ </subsection>
+ <subsection name="elemType">
+ <p>The <code>elemType</code> indicates the type of data
+ represented in the profile element, synonymous to the
+ ISO/IEC 11179 <code>Datatype</code> attribute. The permissible
+ values are:
+ </p>
+
+ <ul>
+ <li><code>boolean</code></li>
+ <li><code>character</code></li>
+ <li><code>date_time</code></li>
+ <li><code>enumerated</code></li>
+ <li><code>integer</code></li>
+ <li><code>ordinal</code></li>
+ <li><code>rational</code></li>
+ <li><code>scaled</code></li>
+ <li><code>real</code></li>
+ <li><code>complex</code></li>
+ <li><code>state</code></li>
+ <li><code>void</code></li>
+ </ul>
+
+ <p>This element is optional within a profile element. When
+ it's not present, the profile element merely indicates that
+ the resource's content possesses the attribute, but more is
+ not known.
+ </p>
+ </subsection>
+
+ <subsection name="elemUnit">
+ <p>The <code>elemUnit</code> indicates the units associated with
+ the values of the data element. This element is synonymous
+ to the ISO/IEC 11179 attribute <code>unit.of.quantity</code>.
+ Values for this optional element should be selected from
+ standardized tables of units.
+ </p>
+ </subsection>
+
+ <subsection name="elemEnumFlag, elemValue, elemMinValue, and
elemMaxValue">
+ <p>The <code>elemEnumFlag</code> tells how possible values of the
+ profile element are specified. It works with the
+ <code>elemValue</code>, <code>elemMinValue</code>, and
+ <code>elemMaxValue</code> elements:
+ </p>
+
+ <ul>
+ <li>If the <code>elemEnumFlag</code>'s value is <code>T</code> and
+ one or more <code>elemValue</code>s appear, then the values
+ listed are the valid values of the element.
+ </li>
+ <li>If the value is <code>F</code>, then a closed range of
+ values bounded by the profile's <code>elemMinValue</code> and
+ <code>elemMaxValue</code> elements indicates the valid values.
+ </li>
+ <li>If the value is <code>T</code> but no <code>elemValue</code>s
+ appear, then it means that any value is a valid
+ value for the resource.
+ </li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="elemSynonym">
+ <p>Often, a characteristic of a resource will go by several
+ names, especially between scientific disciplines. What one
+ person may call <i>latitude</i>, another may call <i>x
+ coordinate</i>, for example. By specifiyng synonyms for a
+ profile element, you can assist in automatic correlation of
+ results and cross-disciplinary discovery.
+ </p>
+
+ <p>The <code>elemSynonym</code> provides a way to do just that.
+ Zero or more <code>elemSynonym</code>s may appear in a profile
+ element. The values of this element are names from data
+ dictionaries other than the discipline data dictionary
+ hosting the profile.
+ </p>
+ </subsection>
+ <subsection name="elemObligation">
+ <p>The <code>elemObligation</code> tells whether the data element
+ is required to always or sometimes be present. This element
+ is synonymous to the ISO/IEC 11179 attribute
+ <code>Obligation</code>, and is optional within a profile
+ element.
+ </p>
+
+ <p>The legal values for this element are <code>Required</code> and
+ <code>Optional</code>, with the obvious meanings.
+ </p>
+ </subsection>
+ <subsection name="elemComment">
+ <p>The <code>elemComment</code> field provides a remark concerning
+ the application of the data element. This element is
+ synonymous to the ISO/IEC 11179 attribute <code>Comment</code>,
+ and is optional within a profile element.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Metadata about the Profile">
+ <p>For a profile server to manage a set of profiles, it's
+ necessary to have metadata contained within the profile that
+ describes the profile itself. This metadata, collectively
+ called the profile attributes, or <code>profAttributes</code>,
+ serves that purpose.
+ </p>
+
+ <p>Most of the elements within the <code>profAttributes</code> are
+ optional. This sections describes each of them.
+ </p>
+
+ <subsection name="profId">
+ <p>The <code>profId</code> serves to give a unique identifier to
+ the profile. It should be expressed as a URI, and often as
+ an URN.
+ </p>
+ </subsection>
+ <subsection name="profVersion">
+ <p>The <code>profVersion</code> identifies the version number of
+ the profile.
+ </p>
+ </subsection>
+ <subsection name="profType">
+ <p>The <code>profType</code> identifies the type of the profile.
+ The type that typically appears here is <code>profile</code>,
+ meaning the profile is a profile (obviously).
+ </p>
+
+ <p>Another type that can be here is <code>dataDict</code>, which
+ indicates that the profile doesn't describe a resource, but
+ instead is a data dictionary for other profiles. Such a
+ profile's composition elements name the expected profile
+ elements and ranges of valid valuese that will appear in
+ other profiles. The <code>profDataDictId</code> element
+ identifies the profile serving as its data dictionary.
+ </p>
+ </subsection>
+ <subsection name="profStatusId">
+ <p>The <code>profStatusId</code> identifies the state of the
+ profile. Profiles may be either <code>active</code> or
+ <code>inactive</code>. An inactive profile is likely maintained
+ for historical or exemplary reasons but is otherwise not
+ currently used for searches or resource descriptions.
+ </p>
+ </subsection>
+ <subsection name="profSecurityType">
+ <p>The <code>profSecurityType</code> identifies whether the
+ information contained in the profile may be of a sensitive
+ nature. Any string is valid here as the current OODT
+ software does not use this field.
+ </p>
+ </subsection>
+ <subsection name="profParentId">
+ <p>The <code>profParentId</code> optionally identifies the URI of
+ the parent of this profile. Profiles may be arranged
+ hierarchically in a singly rooted tree in a forest.
+ </p>
+ </subsection>
+ <subsection name="profChildId">
+ <p>The <code>profChildId</code>
+ identifies zero or more children (by duplicating the element) of
+ this profile.
+ </p>
+ </subsection>
+ <subsection name="profRegAuthority">
+ <p>The <code>profRegAuthority</code>
+ names the registration authority responsible for authoring and
+ maintaining the profile.
+ </p>
+ </subsection>
+ <subsection name="profRevisionNote">
+ <p>The <code>profRevisionNote</code> appears zero or more times in
+ the profile to describe changes made to it over time. The
+ notes are free form text, and each element is ordered from
+ newest to oldest note.
+ </p>
+ </subsection>
+ <subsection name="profDataDictId">
+ <p>The <code>profDataDictId</code>
+ identifies the profile providing a data dictionary to the
+ current profile.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Describing Resources">
+ <p>Let's take a look at how profiles would describe resources by
+ looking at an example set of scientific data. Suppose you
+ archive high temperature data for your weather service; this
+ data comes in the form of tables of latitude/longitude
+ locations and the high temperature recorded at each point.
+ Since you're archiving daily high temperatures, there's one
+ table per day, so each day's table is a discrete resource.
+ Let's say you've got just three days of data so far, though,
+ and it looks like this (to keep things simple).
+ </p>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Day Number</th>
+ <th>Lat</th>
+ <th>Lon</th>
+ <th>High Temp</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr><td
rowspan="3">1</td><td>104.1</td><td>39.2</td><td>26.5</td></tr>
+ <tr><td>110.3</td><td>42.4</td><td>29.9</td></tr>
+ <tr><td>121.5</td><td>45.6</td><td>23.3</td></tr>
+
+ <tr><td
rowspan="3">2</td><td>104.1</td><td>39.2</td><td>31.5</td></tr>
+ <tr><td>110.3</td><td>42.4</td><td>30.9</td></tr>
+ <tr><td>121.5</td><td>45.6</td><td>27.5</td></tr>
+
+ <tr><td
rowspan="3">2</td><td>104.1</td><td>39.2</td><td>20.8</td></tr>
+ <tr><td>110.3</td><td>42.4</td><td>19.5</td></tr>
+ </tbody>
+ </table>
+
+ <p>(On day #3, vandals destroyed the weather sensor station at
+ (121.5, 45.6), so there are only two measurements that day.)
+ </p>
+
+ <p>To make profiles for each day's of data, let's gather some
+ data that will be common to all of them. First, say the
+ weather service's OID is 2.6.1.9, and for all collected data
+ the weather service has reserved an OID 2.6.1.9.2, high
+ temperature measurements 2.6.1.9.2.1. They choose to make a
+ URI for each dataset,
+ <code>urn:weather:data:highs:<var>day-number</var></code>
+ where <var>day-number</var> is the day number of the data.
+ The official creator for all this data will be "Weather
+ Service", under subject keywords "weather", "temperatures",
+ and "measurements". They'll also make the data tables
+ accessible as web documents in MIME format
+ <code>text/tab-separated-values</code> at the address
+ <code>http://weather.gov/data/highs/<var>day-number</var>.txt</code>.
+ </p>
+
+ <p>Here, then, is the profile for the day 1:</p>
+
+ <source><![CDATA[<profile>
+ <profAttributes>
+ <profId>2.6.1.9.2.1.1</profId>
+ <profType>profile</profType>
+ <profStatusId>active</profStatusId>
+ </profAttributes>
+ <resAttributes>
+ <Identifier>urn:weather:data:highs:1</Identifier>
+ <Title>High Temperatures - Day 1</Title>
+ <Format>text/tab-separated-values</Format>
+ <Creator>Weather Service</Creator>
+ <Subject>weather</Subject>
+ <Subject>temperatures</Subject>
+ <Subject>measurements</Subject>
+ <resContext>NOAA.NWS.Data</resContext>
+ <resClass>data.granule</resClass>
+ <resLocation>http://weather.gov/data/highs/1.txt</resLocation>
+ </resAttributes>
+ <profElement>
+ <elemName>latitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>104.1</elemMinValue>
+ <elemMaxValue>121.5</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>longitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>39.2</elemMinValue>
+ <elemMaxValue>45.6</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>temperature</elemName>
+ <elemType>real</elemType>
+ <elemUnit>celsius</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>23.3</elemMinValue>
+ <elemMaxValue>29.9</elemMaxValue>
+ </profElement>
+</profile>]]></source>
+
+ <p>Someone searching for a high temperature that exceeded 25
+ degrees, for example, would find this as a matching
+ resource, as the <code>elemMinValue</code> for
+ <code>temperature</code> is 23.3, and 25 is over that.
+ </p>
+
+ <p>Here are all three profiles in one document:</p>
+
+ <source><![CDATA[<profiles>
+ <profile>
+ <profAttributes>
+ <profId>2.6.1.9.2.1.1</profId>
+ <profType>profile</profType>
+ <profStatusId>active</profStatusId>
+ </profAttributes>
+ <resAttributes>
+ <Identifier>urn:weather:data:highs:1</Identifier>
+ <Title>High Temperatures - Day 1</Title>
+ <Format>text/tab-separated-values</Format>
+ <Creator>Weather Service</Creator>
+ <Subject>weather</Subject>
+ <Subject>temperatures</Subject>
+ <Subject>measurements</Subject>
+ <resContext>NOAA.NWS.Data</resContext>
+ <resClass>data.granule</resClass>
+ <resLocation>http://weather.gov/data/highs/1.txt</resLocation>
+ </resAttributes>
+ <profElement>
+ <elemName>latitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>104.1</elemMinValue>
+ <elemMaxValue>121.5</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>longitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>39.2</elemMinValue>
+ <elemMaxValue>45.6</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>temperature</elemName>
+ <elemType>real</elemType>
+ <elemUnit>celsius</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>23.3</elemMinValue>
+ <elemMaxValue>29.9</elemMaxValue>
+ </profElement>
+ </profile>
+ <profile>
+ <profAttributes>
+ <profId>2.6.1.9.2.1.2</profId>
+ <profType>profile</profType>
+ <profStatusId>active</profStatusId>
+ </profAttributes>
+ <resAttributes>
+ <Identifier>urn:weather:data:highs:2</Identifier>
+ <Title>High Temperatures - Day 2</Title>
+ <Format>text/tab-separated-values</Format>
+ <Creator>Weather Service</Creator>
+ <Subject>weather</Subject>
+ <Subject>temperatures</Subject>
+ <Subject>measurements</Subject>
+ <resContext>NOAA.NWS.Data</resContext>
+ <resClass>data.granule</resClass>
+ <resLocation>http://weather.gov/data/highs/2.txt</resLocation>
+ </resAttributes>
+ <profElement>
+ <elemName>latitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>104.1</elemMinValue>
+ <elemMaxValue>121.5</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>longitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>39.2</elemMinValue>
+ <elemMaxValue>45.6</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>temperature</elemName>
+ <elemType>real</elemType>
+ <elemUnit>celsius</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>27.5</elemMinValue>
+ <elemMaxValue>31.5</elemMaxValue>
+ </profElement>
+ </profile>
+ <profile>
+ <profAttributes>
+ <profId>2.6.1.9.2.1.3</profId>
+ <profType>profile</profType>
+ <profStatusId>active</profStatusId>
+ </profAttributes>
+ <resAttributes>
+ <Identifier>urn:weather:data:highs:3</Identifier>
+ <Title>High Temperatures - Day 3</Title>
+ <Format>text/tab-separated-values</Format>
+ <Creator>Weather Service</Creator>
+ <Subject>weather</Subject>
+ <Subject>temperatures</Subject>
+ <Subject>measurements</Subject>
+ <resContext>NOAA.NWS.Data</resContext>
+ <resClass>data.granule</resClass>
+ <resLocation>http://weather.gov/data/highs/3.txt</resLocation>
+ </resAttributes>
+ <profElement>
+ <elemName>latitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>104.1</elemMinValue>
+ <elemMaxValue>110.3</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>longitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>39.2</elemMinValue>
+ <elemMaxValue>42.4</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>temperature</elemName>
+ <elemType>real</elemType>
+ <elemUnit>celsius</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>19.5</elemMinValue>
+ <elemMaxValue>20.8</elemMaxValue>
+ </profElement>
+ </profile>
+</profiles>]]></source>
+
+ <p>Given this set of profiles, a profile search for resources
+ with <code>latitude > 120.0</code> would match profiles
+ for day 1 and 2, but not day 3. Actual profile searches are
+ possible by taking the above document and loading it into
+ the <code>LightweightProfileHandler</code>, yet that becomes
+ impractical for many many profiles, as it holds all of the
+ profile objects in memory and "searches" them in place.
+ More likely, data such as these would be stored in a
+ relational database, and the matching profiles would be
+ generated on demand.
+ </p>
+
+ <p>Let's make one more profile, a profile that describes
+ <em>the entire collection</em>:
+ </p>
+
+ <source><![CDATA[
+ <profile>
+ <profAttributes>
+ <profId>2.6.1.9.2.1</profId>
+ <profType>profile</profType>
+ <profStatusId>active</profStatusId>
+ </profAttributes>
+ <resAttributes>
+ <Identifier>urn:weather:data:highs:index</Identifier>
+ <Title>High Temperatures</Title>
+ <Format>text/tab-separated-values</Format>
+ <Creator>Weather Service</Creator>
+ <Subject>weather</Subject>
+ <Subject>temperatures</Subject>
+ <Subject>measurements</Subject>
+ <resContext>NOAA.NWS.Data</resContext>
+ <resClass>system.profileServer</resClass>
+ <resLocation>urn:weather:data:highs:ProfileServer</resLocation>
+ </resAttributes>
+ <profElement>
+ <elemName>latitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>104.1</elemMinValue>
+ <elemMaxValue>121.5</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>longitude</elemName>
+ <elemType>real</elemType>
+ <elemUnit>degree</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>19.5</elemMinValue>
+ <elemMaxValue>31.5</elemMaxValue>
+ </profElement>
+ <profElement>
+ <elemName>temperature</elemName>
+ <elemType>real</elemType>
+ <elemUnit>celsius</elemUnit>
+ <elemEnumFlag>F</elemEnumFlag>
+ <elemMinValue>19.5</elemMinValue>
+ <elemMaxValue>31.5</elemMaxValue>
+ </profElement>
+ </profile>]]></source>
+
+ <p>Note that in addition to several changes in the resource
+ attributes, we've also changed the profile elements to
+ cover the entire range of latitude, longitude, and
+ temperature in the entire data set. So, for temperature,
+ the lowest high temperature for all three days was 19.5,
+ and the highest was 31.5. Now, a profile search can for
+ temperatures greater than 30 will match the profile for
+ the whole collection, as well as the profile for day #2.
+ </p>
+
+ <p>In fact, the OODT framework supports automatic drill-down of
+ this kind. The <a href="/grid-query/">Query Service</a>, upon
+ encountering a matching profile, checks to see if the
+ <code>resClass</code> is <code>system.profileServer</code>,
+ and if so, will pass the query to the profile server at the
+ <code>resLocation</code> in the matched profile. It will
+ gather up all matching profiles and return them to the user.
+ In this way, it can follow a directed graph of linked profile
+ servers (automatically avoiding cycles), and gathering more
+ and more results.
+ </p>
+ </section>
+ </body>
+</document>
Propchange: oodt/trunk/profile/src/site/xdoc/info/index.xml
------------------------------------------------------------------------------
svn:executable = *
Added: oodt/trunk/profile/src/site/xdoc/querying/index.xml
URL:
http://svn.apache.org/viewvc/oodt/trunk/profile/src/site/xdoc/querying/index.xml?rev=1079088&view=auto
==============================================================================
--- oodt/trunk/profile/src/site/xdoc/querying/index.xml (added)
+++ oodt/trunk/profile/src/site/xdoc/querying/index.xml Tue Mar 8 02:13:07 2011
@@ -0,0 +1,203 @@
+<?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>Querying Profile Elements</title>
+ <author email="[email protected]">Sean Kelly</author>
+ </properties>
+ <!-- Four Carry Nuts - Hexagon -->
+ <body>
+ <section name="Querying Profile Elements">
+
+ <p>As desribed in <a href="../info/">Information Captured in a
+ Profile</a>, profile elements describe the composition of a
+ resource using metadata descriptions taken from the <a
+ href="http://metadata-standards.org/11179/";>ISO/IEC 11179
+ standards</a>. The profile elements catalog lists of valid
+ values, minimum and maximum values, data types, and so forth.
+ </p>
+
+ <p>As you develop a profile handler to perform queries and
+ generate profiles, you'll encounter three cases when querying
+ profile elements or the data sources they describe:
+ </p>
+
+ <ul>
+ <li>Querying ranges of values</li>
+ <li>Querying enumerated values</li>
+ <li>Querying unspecified profile lements</li>
+ </ul>
+ </section>
+
+ <section name="Queries Against Ranges">
+ <p>Ranged profile elements are those that describe an attribute
+ of a resource's composition in terms of a continuous space of
+ valid values. In the Java implementation, there's a subclass
+ of <code>ProfileElement</code> to represent such ranges:
+ <code>RangedProfileElement</code>. In the XML representation,
+ the <code><elemEnumFlag></code> is <code>F</code> and
+ there are values listed for <code><elemMinValue></code>
+ and <code><elemMaxValue></code>.
+ </p>
+
+ <p>An example of a ranged profile element might be:</p>
+ <table>
+ <tbody>
+ <tr><td>Name:</td><td>temperature</td></tr>
+ <tr><td>Description:</td><td>Temperatures measured using
+ oral, medical-use, alcohol-based thermometer.</td></tr>
+ <tr><td>Type:</td><td>real</td></tr>
+ <tr><td>Unit:</td><td>kelvin</td></tr>
+ <tr><td>Enumeration flag:</td><td>false</td></tr>
+ <tr><td>Min value:</td><td>282.31</td></tr>
+ <tr><td>Max value:</td><td>301.45</td></tr>
+ </tbody>
+ </table>
+
+ <p>When you're generating a profile (or querying a similar
+ metadata model) with a ranged element, queries should match if
+ the sought value occurs within the given, inclusive range. If
+ it's a negative query, then it should match if the sought
+ value <em>doesn't</em> occur within the range.
+ </p>
+
+ <p>Here's an example. Suppose you have a ranged profile element
+ called <code>lumens</code> and its minimum value is 10 and its
+ maximum value is 20. Here's a table that shows queries and
+ whether they match:
+ </p>
+
+ <table>
+ <thead>
+ <tr><th>Query</th><th>Match?</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>lumens = 12</td><td>Yes, since 12 is between 10 and
20</td></tr>
+ <tr><td>lumens = 45</td><td>No, since 45 is above 20</td></tr>
+ <tr><td>lumens != 12</td><td>Yes, since there are <em>other
values</em> in the range 10..20 that match, such as 13, 14, 12.1, etc.</td></tr>
+ <tr><td>lumens != 45</td><td>Yes, since are an infinite number of
values in the range 10..22 that are not 45</td></tr>
+ <tr><td>lumens != 10</td><td>Yes</td></tr>
+ <tr><td>lumens < 45</td><td>Yes</td></tr>
+ <tr><td>lumens > 15</td><td>Yes</td></tr>
+ <tr><td>lumens > 35</td><td>No; the highest lumen value is
20</td></tr>
+ <tr><td>lumens LIKE 12</td><td>Maybe</td></tr>
+ </tbody>
+ </table>
+
+ <p>The "LIKE" relational operator defined by the XMLQuery query
+ langauge was meant for string comparisons, yet there's nothing
+ in the software that prevents it from being presented for
+ ranged queries. The choice of whether to match it is up to you.
+ </p>
+ </section>
+
+ <section name="Queries Against Enumerated Values">
+ <p>Enumerated profile elements are those that describe an
+ attribute of a resource's composition in terms of a discrete
+ list of valid values. In the Java implementation, there's a
+ subclass of <code>ProfileElement</code> to represent such
+ ranges: <code>EnumeratedProfileElement</code>. In the XML
+ representation, the <code><elemEnumFlag></code> is
+ <code>T</code> and there are one or more
+ <code><elemValue></code> elements.
+ </p>
+
+ <p>An example of an enumerated profile element might be:</p>
+ <table>
+ <tbody>
+ <tr><td>Name:</td><td>zone</td></tr>
+ <tr><td>Description:</td><td>City Planning Commission zoning code for
permitted land use.</td></tr>
+ <tr><td>Type:</td><td>string</td></tr>
+ <tr><td>Unit:</td><td>code</td></tr>
+ <tr><td>Enumeration flag:</td><td>true</td></tr>
+ <tr><td>Value:</td><td>A</td></tr>
+ <tr><td>Value:</td><td>B1</td></tr>
+ <tr><td>Value:</td><td>B2</td></tr>
+ <tr><td>Value:</td><td>B4</td></tr>
+ <tr><td>Value:</td><td>C</td></tr>
+ <tr><td>Value:</td><td>H</td></tr>
+ <tr><td>Value:</td><td>PDD</td></tr>
+ <tr><td>Value:</td><td>R2</td></tr>
+ <tr><td>Value:</td><td>R3</td></tr>
+ <tr><td>Value:</td><td>R4</td></tr>
+ <tr><td>Value:</td><td>R5</td></tr>
+ </tbody>
+ </table>
+
+ <p>When you're generating a profile (or querying a similar
+ metadata model) with an enumerated element, queries should
+ match if the sought value appears as one of the listed
+ elements.
+ </p>
+
+ <p>Here's an example. Suppose you have an profile element
+ called <code>planet</code> that has as valid values
+ <code>Mercury</code>, <code>Venus</code>, <code>Earth</code>,
+ and <code>Mars</code>. Here's a table that shows queries and
+ whether they match:
+ </p>
+
+ <table>
+ <thead>
+ <tr><th>Query</th><th>Match?</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>planet = Mercury</td><td>Yes</td></tr>
+ <tr><td>planet = Jupiter</td><td>No</td></tr>
+ <tr><td>planet != Mercury</td><td>Yes since Earth, Venus, and Mars
are all not Mercury</td></tr>
+ <tr><td>planet != Jupiter</td><td>Yes since there are 4 planets which
are all not Jupiter</td></tr>
+ <tr><td>planet < Earth</td><td>Maybe</td></tr>
+ <tr><td>planet LIKE %E%</td><td>Yes, since all four planets have an E
in them (without regard to case)</td></tr>
+ <tr><td>planet NOTLIKE %E%</td><td>No, since all four planets have an
E in them</td></tr>
+ </tbody>
+ </table>
+
+ <p>Relational ordering is not specified by the profile model, so whether
+ a query like <code>planet < Earth</code> matches is up to you.
+ </p>
+ </section>
+
+ <section name="Querying Against Unspecified Values">
+ <p>An unspecific profile element indicates only the
+ <em>presence</em> of an attribute in the composition of a
+ resource, and nothing else. In the Java implementation,
+ there's a subclass of <code>ProfileElement</code> to represent
+ this, <code>UnspecifiedProfileElement</code>. In the XML
+ representation, the <code><elemEnumFlag></code> is
+ <code>T</code> and there are zero
+ <code><elemValue></code> elements.
+ </p>
+
+ <p>Unspecified profile elements can be useful where you have
+ profiles not describing single resources, but entire
+ collections of resources. For example, you may have ranged
+ profile elements called <code>temperature</code> for each
+ temperature resource. But if there are a billion resources,
+ then determining the minimum and maximum temperature for the
+ profile of the entire collection might be painful, in which
+ case you can say that the collection has a
+ <code>temperature</code> attribute by using an unspecified
+ profile for the element for the collection.
+ </p>
+
+ <p>Queries against unspecified elements always match, regardless
+ what the query is.
+ </p>
+ </section>
+ </body>
+</document>
Propchange: oodt/trunk/profile/src/site/xdoc/querying/index.xml
------------------------------------------------------------------------------
svn:executable = *
Added: oodt/trunk/profile/src/site/xdoc/rep/index.xml
URL:
http://svn.apache.org/viewvc/oodt/trunk/profile/src/site/xdoc/rep/index.xml?rev=1079088&view=auto
==============================================================================
--- oodt/trunk/profile/src/site/xdoc/rep/index.xml (added)
+++ oodt/trunk/profile/src/site/xdoc/rep/index.xml Tue Mar 8 02:13:07 2011
@@ -0,0 +1,334 @@
+<?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="[email protected]">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>
Propchange: oodt/trunk/profile/src/site/xdoc/rep/index.xml
------------------------------------------------------------------------------
svn:executable = *
