org.dlese.dpc.vocab
Class MetadataVocab

java.lang.Object
  org.dlese.dpc.vocab.MetadataVocab

All Implemented Interfaces:

ContentHandler

public class MetadataVocab

extends Object

implements ContentHandler

Facilitates interface representation of metadata vocabulary.

Controlled vocabulary is stored in XML files and read into the hierarchical class data structure via a SAX reader. Various methods are provided for representing the vocabulary through a Web interface (HTML/Javascript) using JSP scriptlet calls or custom tags (see org.dlese.dpc.vocab.tags).

Methods that might be usefull outside of any particular UI are as follows:

• getFieldSystemId
• getFieldValueIdPairExists
• getFieldValueSystemId
• getMetaNameOfId
• getUiLabelOf
• getUiLabelOfSystemIds

Method descriptions often use the following terms:

• Field - The first half of the field/value vocabulary scheme
• Value - The second half of the field/value vocabulary scheme
• Metadata name - The descriptive name given to a vocabulary field or value
• Encoded Id - The compact unique identifier that the management system assigns to a particular vocabulary field or value (sometimes referred to as "system Id")

The last two terms are often used in combination with the first two. For example, "Encoded field Id" refers to the unique system Id of a vocabulary field.

Most public methods take an initial parameter called "system", which is a period-seperated trio that corresponds to the system/interface/language attributes of the XML files. To retreive values associated with the english language version of the default DDS interface, for example, one would pass the string "dds.default.en-us".

Almost all of the public methods that produce lists for UI display take a parameter named "group". This is a colon-seperated identifier of the spot within the vocabulary hierarchy which is being requested for display. Passing "topic:geography" would return a representation of only the metadata entries that fall under the "geography" sub-heading in the "topic" category. The colon is not always necessary, however--passing simply "topic" will return a represenation of all entries in the "topic" category.

Author:

Ryan Deardorff

Constructor Summary

MetadataVocab(String sqlDriver, String sqlURL, String sqlUser, String sqlPassword)
Constructor for the MetadataVocab object

Method Summary

void	characters(char[] ch, int start, int length) (SAX) Element data (characters between tags)
void	charactersDefinition(char[] ch, int start, int length) (SAX) Element data for definitions
void	charactersUI(char[] ch, int start, int length) (SAX) Element data for UIs
void	doneLoading() When all vocabs are loaded, generate the Lucene queries, register all current UI labels into the database, and close any database connection
void	endDocument() (SAX) Invoked at the end of parsing.
void	endElement(String namespaceURI, String localName, String qName) (SAX) Invoked upon closing tag of an XML element
void	endElementDefinition(String namespaceURI, String localName, String qName) (SAX) End element for definitions
void	endElementUI(String namespaceURI, String localName, String qName) (SAX) End element for UIs
void	endPrefixMapping(String prefix) (SAX) Required by SAX, but not used here
ArrayList	getErrors() Gets the errors attribute of the MetadataVocab object
String	getFieldSystemId(String field) Gets the encoded field Id of the given metadata field
boolean	getFieldValueIdPairExists(String fieldId, String valueId) Does a vocabulary definition exist for the given encoded field/value Ids?
String	getFieldValueSystemId(String field, String value) Gets the encoded value Id of the given metadata field/value pair
ArrayList	getMessages() Gets the messages attribute of the MetadataVocab object
String	getMetaNameOfId(String system, String fieldId, String valueId) Gets the metadata value or field name of the given encoded field and value Ids.
String	getTopLevelAbbrevLabelOf(String system, String metadataField, String systemFieldId, String systemValueId) Gets the topLevelAbbrevLabelOf attribute of the MetadataVocab object
String	getUiLabelOf(String system, String metadataField, String metadataValue) Gets the full (non-abbreviated) UI label of the given metadata field/value pair
String	getUiLabelOf(String system, String metadataField, String metadataValue, boolean abbreviated) Gets the UI label of the given metadata field/value pair
String	getUiLabelOfSystemIds(String system, String systemFieldId, String systemValueId) Gets the full (non-abbreviated) UI label of the given encoded field/value Id pair
String	getUiLabelOfSystemIds(String system, String systemFieldId, String systemValueId, boolean abbreviated) Gets the UI label of the given encoded field/value Id pair
String	getVocabCheckbox(String groupTop, String value, String label, PageContext page) Returns a SINGLE HTML CHECKBOX input of the specified part of the vocabulary.
String	getVocabCheckboxes(String system, String group, int size, String tdWidth, boolean skipTopRow, PageContext page) Returns an HTML TABLE of CHECKBOX inputs of the specified part of the vocabulary.
String	getVocabCheckboxesAllClearLinks(String system, String group, int numCheckboxes, HttpSession session) Returns HTML code that displays the "All | Clear" links for checkboxes.
String	getVocabHiddenInputs(String system, String group, PageContext page) Generates HTML HIDDEN inputs of the specified part of the vocabulary.
String	getVocabHistogram(String system, String group, PageContext page, String addQuery, String imgPrefix, String tableWidth) Generates an HTML "histogram" view of the specified part of the vocabulary.
ArrayList	getVocabNodes(String system, String group) Gets the vocabNodes attribute of the MetadataVocab object
String	getVocabSelectList(String system, String group, int size, PageContext page) Returns an HTML SELECT list of the specified part of the vocabulary.
String	getVocabTreeMenu(String system, String language, String group, String x, String y, PageContext page) Generates a Javascript Tree Menu (collapsable hierarchy) of the specified part of the vocabulary
boolean	hasSubtotalsGreaterThanZero(VocabList list, String topMetaName, HashMap histogramTotals) Does this list have values (or sub-values) that total > 0? If not, sub-headers don't render.
void	ignorableWhitespace(char[] ch, int start, int length) (SAX) Reports any whitespace that is ignored because it falls outside of the DTD or schema definition--usefull for re-generating the file with indents intact.
void	processingInstruction(String target, String data) (SAX) Required by SAX, but not used here
void	reportError(String err) Log an error
void	reportMessage(String msg) Log a message
String	resetJSCount(HttpSession session) Reset the counter that keeps track of how many checkboxes have been rendered so far by getVocabCheckboxes().
void	setDocumentLocator(Locator locator) (SAX) Sets the SAX locator, which indicates the current position of the parser within the document (line number, column number).
void	setParsingDefinitions(boolean bool) (SAX) Not strictly part of the SAX interface, but we use this to figure out which type of XML we're parsing (definitions/terms vs.
void	setVocabHistogramHighestCountFromGroup(String system, String group, LuceneIndex index, String addQuery, PageContext page, boolean onlyIfGreaterThanCurrent) Gets the highest total count within the given vocab group, for use in the histogram generation
void	skippedEntity(String name) (SAX) Required by SAX, but not used here
void	startDocument() (SAX) Invoked at the start of any document parse
void	startElement(String namespaceURI, String localName, String qName, Attributes atts) (SAX) Invoked upon opening tag of an XML element
void	startElementDefinition(String namespaceURI, String localName, String qName, Attributes atts) (SAX) Invoked upon opening tag of a definitions XML element
void	startElementUI(String namespaceURI, String localName, String qName, Attributes atts) (SAX) Start element for the UI files
void	startPrefixMapping(String prefix, String uri) (SAX) Required by SAX, but not used here

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetadataVocab

public MetadataVocab(String sqlDriver,
                     String sqlURL,
                     String sqlUser,
                     String sqlPassword)

Constructor for the MetadataVocab object

Parameters:

sqlDriver -

sqlURL -

sqlUser -

sqlPassword -

Method Detail

getMessages

public ArrayList getMessages()

Gets the messages attribute of the MetadataVocab object

Returns:

The messages value

getErrors

public ArrayList getErrors()

Gets the errors attribute of the MetadataVocab object

Returns:

The errors value

getMetaNameOfId

public String getMetaNameOfId(String system,
                              String fieldId,
                              String valueId)

Gets the metadata value or field name of the given encoded field and value Ids. Pass "" (empty string) for valueId to have it return the metadata field name (instead of value).

Parameters:

system - Vocabulary system/interface/language trio, i.e. "dds.default.en-us"

fieldId - Encoded vocabulary field Id

valueId - Encoded vocabulary value Id

Returns:

The metaNameOfId value

getFieldValueIdPairExists

public boolean getFieldValueIdPairExists(String fieldId,
                                         String valueId)

Does a vocabulary definition exist for the given encoded field/value Ids?

Parameters:

fieldId - Encoded vocabulary field Id

valueId - Encoded vocabulary value Id

Returns:

The fieldValueIdPairExists value

getFieldValueSystemId

public String getFieldValueSystemId(String field,
                                    String value)
                             throws Exception

Gets the encoded value Id of the given metadata field/value pair

Parameters:

field - Metadata field name

value - Metadata value name

Returns:

The encoded value Id

Throws:

Exception

getFieldSystemId

public String getFieldSystemId(String field)
                        throws Exception

Gets the encoded field Id of the given metadata field

Parameters:

field - Metadata field name

Returns:

The encoded field Id

Throws:

Exception

getUiLabelOf

public String getUiLabelOf(String system,
                           String metadataField,
                           String metadataValue,
                           boolean abbreviated)

Gets the UI label of the given metadata field/value pair

Parameters:

system - Vocabulary system/interface/language trio, i.e. "dds.default.en-us"

metadataField - Metadata field name

metadataValue - Metadata value name

abbreviated - Return the abbreviated form of the UI label?

Returns:

The user interface label associated with the given vocabulary value

getUiLabelOf

public String getUiLabelOf(String system,
                           String metadataField,
                           String metadataValue)

Gets the full (non-abbreviated) UI label of the given metadata field/value pair

Parameters:

system - Vocabulary system/interface/language trio, i.e. "dds.default.en-us"

metadataField - Metadata field name

metadataValue - Metadata value name

Returns:

The user interface label associated with the given vocabulary value

getUiLabelOfSystemIds

public String getUiLabelOfSystemIds(String system,
                                    String systemFieldId,
                                    String systemValueId,
                                    boolean abbreviated)

Gets the UI label of the given encoded field/value Id pair

Parameters:

system - Vocabulary system/interface/language trio, i.e. "dds.default.en-us"

systemFieldId - Encoded field Id

systemValueId - Encoded value Id

abbreviated - Return the abbreviated form of the UI label?

Returns:

The user interface label associated with the given vocabulary value

getUiLabelOfSystemIds

public String getUiLabelOfSystemIds(String system,
                                    String systemFieldId,
                                    String systemValueId)

Gets the full (non-abbreviated) UI label of the given encoded field/value Id pair

Parameters:

system - Vocabulary system/interface/language trio, i.e. "dds.default.en-us"

systemFieldId - Encoded field Id

systemValueId - Encoded value Id

Returns:

The user interface label associated with the given vocabulary value

getTopLevelAbbrevLabelOf

public String getTopLevelAbbrevLabelOf(String system,
                                       String metadataField,
                                       String systemFieldId,
                                       String systemValueId)

Gets the topLevelAbbrevLabelOf attribute of the MetadataVocab object

Parameters:

system -

metadataField -

systemFieldId -

systemValueId -

Returns:

The topLevelAbbrevLabelOf value

getVocabNodes

public ArrayList getVocabNodes(String system,
                               String group)

Gets the vocabNodes attribute of the MetadataVocab object

Parameters:

system -

group -

Returns:

The vocabNodes value

getVocabSelectList

public String getVocabSelectList(String system,
                                 String group,
                                 int size,
                                 PageContext page)

Returns an HTML SELECT list of the specified part of the vocabulary.

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

size - size (height) of the SELECT list

page - JSP PageContext

system -

Returns:

The vocabSelectList value

getVocabCheckboxes

public String getVocabCheckboxes(String system,
                                 String group,
                                 int size,
                                 String tdWidth,
                                 boolean skipTopRow,
                                 PageContext page)

Returns an HTML TABLE of CHECKBOX inputs of the specified part of the vocabulary.

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

size - how many inputs to display before starting a new column in the table

tdWidth - value inserted into the width param of the TD tag

skipTopRow - Should the top row of checkboxes (next to All | Clear) be skipped?

page - JSP PageContext

system -

Returns:

the HTML code

getVocabCheckbox

public String getVocabCheckbox(String groupTop,
                               String value,
                               String label,
                               PageContext page)

Returns a SINGLE HTML CHECKBOX input of the specified part of the vocabulary.

Parameters:

groupTop - Top-level vocab group

value - vocab value

label - UI label

page - JSP PageContext

Returns:

the HTML code

getVocabCheckboxesAllClearLinks

public String getVocabCheckboxesAllClearLinks(String system,
                                              String group,
                                              int numCheckboxes,
                                              HttpSession session)

Returns HTML code that displays the "All | Clear" links for checkboxes. This is only needed when checkboxes are rendered individually via getVocabCheckbox().

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

numCheckboxes - number of checkboxes that will be rendered individually

session - JSP Session

system -

Returns:

the HTML/Javascript code

resetJSCount

public String resetJSCount(HttpSession session)

Reset the counter that keeps track of how many checkboxes have been rendered so far by getVocabCheckboxes(). Because getVocabCheckboxes() constructs the "All | Clear" links that set or clear the inputs, and because Javascript uses the index of each checkbox (the order that they appear on the page) to do so, the global jsCount is used to keep track of those indexes, in order to create the calls to the Javascript function telling it what range of inputs need to be set or cleared. On any given page, you MUST call resetJSCount() before making any calls to getVocabCheckboxes(), or the Javascript links won't work!

Parameters:

session - JSP Session

Returns:

the Javascript code that is invoked by the "All | Clear" links

getVocabHistogram

public String getVocabHistogram(String system,
                                String group,
                                PageContext page,
                                String addQuery,
                                String imgPrefix,
                                String tableWidth)

Generates an HTML "histogram" view of the specified part of the vocabulary. The histogram is a sideways bar-graph view of the number of resources in the catalog. This requires making a query to LuceneIndex.numDocs() for each item displayed. Each item in the graph is created as a link that invokes a search of that criteria item.

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

addQuery - query of metadata selected thus far (for "drill-down", not currently used)

page - JSP PageContext

imgPrefix - location of histogram images

system -

tableWidth -

Returns:

the HTML code

hasSubtotalsGreaterThanZero

public boolean hasSubtotalsGreaterThanZero(VocabList list,
                                           String topMetaName,
                                           HashMap histogramTotals)

Does this list have values (or sub-values) that total > 0? If not, sub-headers don't render.

Parameters:

list -

topMetaName -

histogramTotals -

Returns:

setVocabHistogramHighestCountFromGroup

public void setVocabHistogramHighestCountFromGroup(String system,
                                                   String group,
                                                   LuceneIndex index,
                                                   String addQuery,
                                                   PageContext page,
                                                   boolean onlyIfGreaterThanCurrent)

Gets the highest total count within the given vocab group, for use in the histogram generation

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

index - object that returns resource totals via index.numDocs()

addQuery - query of metadata selected thus far

onlyIfGreaterThanCurrent - set the value only if it ends up being greater than the current value

page - JSP PageContext

system - The new vocabHistogramHighestCountFromGroup value

getVocabTreeMenu

public String getVocabTreeMenu(String system,
                               String language,
                               String group,
                               String x,
                               String y,
                               PageContext page)

Generates a Javascript Tree Menu (collapsable hierarchy) of the specified part of the vocabulary

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

system -

x -

y -

page -

language -

Returns:

the Javascript code defining the menu

getVocabHiddenInputs

public String getVocabHiddenInputs(String system,
                                   String group,
                                   PageContext page)

Generates HTML HIDDEN inputs of the specified part of the vocabulary.

Parameters:

group - colon-seperated specifier of the part of the vocab hierarchy which is to be displayed

page - JSP PageContext

system -

Returns:

the HTML code

doneLoading

public void doneLoading()

When all vocabs are loaded, generate the Lucene queries, register all current UI labels into the database, and close any database connection

setParsingDefinitions

public void setParsingDefinitions(boolean bool)

(SAX) Not strictly part of the SAX interface, but we use this to figure out which type of XML we're parsing (definitions/terms vs. UI/groups)

Parameters:

bool - The new parsingDefinitions value

setDocumentLocator

public void setDocumentLocator(Locator locator)

(SAX) Sets the SAX locator, which indicates the current position of the parser within the document (line number, column number). Could be used to indicate the spot where an error occured.

Specified by:

setDocumentLocator in interface ContentHandler

Parameters:

locator - The new saxLocator value

startDocument

public void startDocument()
                   throws SAXException

(SAX) Invoked at the start of any document parse

Specified by:

startDocument in interface ContentHandler

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

(SAX) Invoked at the end of parsing. Rewrite the definitions XML if new Ids have been assigned.

Specified by:

endDocument in interface ContentHandler

Throws:

SAXException

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

(SAX) Invoked upon opening tag of an XML element

Specified by:

startElement in interface ContentHandler

Parameters:

namespaceURI -

localName -

qName -

atts -

Throws:

SAXException

startElementDefinition

public void startElementDefinition(String namespaceURI,
                                   String localName,
                                   String qName,
                                   Attributes atts)
                            throws SAXException

(SAX) Invoked upon opening tag of a definitions XML element

Parameters:

namespaceURI -

localName -

qName -

atts -

Throws:

SAXException

startElementUI

public void startElementUI(String namespaceURI,
                           String localName,
                           String qName,
                           Attributes atts)
                    throws SAXException

(SAX) Start element for the UI files

Parameters:

namespaceURI - XML namespace

localName - local tag name

qName - fully qualified tag name

atts - tag attributes

Throws:

SAXException

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String qName)
                throws SAXException

(SAX) Invoked upon closing tag of an XML element

Specified by:

endElement in interface ContentHandler

Parameters:

namespaceURI - XML namespace

localName - local tag name

qName - fully qualified tag name

Throws:

SAXException

endElementDefinition

public void endElementDefinition(String namespaceURI,
                                 String localName,
                                 String qName)
                          throws SAXException

(SAX) End element for definitions

Parameters:

namespaceURI -

localName -

qName -

Throws:

SAXException

endElementUI

public void endElementUI(String namespaceURI,
                         String localName,
                         String qName)
                  throws SAXException

(SAX) End element for UIs

Parameters:

namespaceURI -

localName -

qName -

Throws:

SAXException

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

(SAX) Element data (characters between tags)

Specified by:

characters in interface ContentHandler

Parameters:

ch -

start -

length -

Throws:

SAXException

charactersDefinition

public void charactersDefinition(char[] ch,
                                 int start,
                                 int length)
                          throws SAXException

(SAX) Element data for definitions

Parameters:

ch -

start -

length -

Throws:

SAXException

charactersUI

public void charactersUI(char[] ch,
                         int start,
                         int length)
                  throws SAXException

(SAX) Element data for UIs

Parameters:

ch - character array

start - starting index of character data

length - length of character data

Throws:

SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

(SAX) Reports any whitespace that is ignored because it falls outside of the DTD or schema definition--usefull for re-generating the file with indents intact.

Specified by:

ignorableWhitespace in interface ContentHandler

Parameters:

ch -

start -

length -

Throws:

SAXException

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

(SAX) Required by SAX, but not used here

Specified by:

startPrefixMapping in interface ContentHandler

Parameters:

prefix -

uri -

Throws:

SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

(SAX) Required by SAX, but not used here

Specified by:

endPrefixMapping in interface ContentHandler

Parameters:

prefix -

Throws:

SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

(SAX) Required by SAX, but not used here

Specified by:

processingInstruction in interface ContentHandler

Parameters:

target -

data -

Throws:

SAXException

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

(SAX) Required by SAX, but not used here

Specified by:

skippedEntity in interface ContentHandler

Parameters:

name -

Throws:

SAXException

reportMessage

public void reportMessage(String msg)

Log a message

Parameters:

msg -

reportError

public void reportError(String err)

Log an error

Parameters:

err -