org.jlab.coda.jevio

Class EvioXMLDictionary

java.lang.Object

org.jlab.coda.jevio.EvioXMLDictionary

All Implemented Interfaces:

INameProvider

public class EvioXMLDictionary
extends java.lang.Object
implements INameProvider

This was developed to read the xml dictionary that Maurizio uses for GEMC. It implements INameProvider, just like all other dictionary readers.

An assumption in the following class is that each unique tag/num/tagEnd group corresponds to an equally unique name. In other words, 2 different groups cannot have the same name. And 2 different names cannot map to the same group.

An entry with only a tag value and no num is allowed. It will match a tag/num pair if no exact match exists but the tag matches. For such an entry, no additional existence of type, format, or description is allowed.

Similarly, an entry with a range of tags is also allowed. In this case, no num and type is allowed. It will match a tag/num pair if no exact match exists but the tag is in the range (inclusive).

Author:

heddle, timmer

Field Summary

Fields

Modifier and Type	Field and Description
java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String>	tagNumMap This is the heart of the dictionary in which a key is composed of a tag/num pair and other entry data and its corresponding value is a name.
java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String>	tagOnlyMap Some dictionary entries have only a tag and no num.
java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String>	tagRangeMap Some dictionary entries have only a tag range and no num.

Fields inherited from interface org.jlab.coda.jevio.INameProvider

NO_NAME_STRING

Constructor Summary

Constructors

Constructor and Description
EvioXMLDictionary(org.w3c.dom.Document domDocument) Create an EvioXMLDictionary from an xml Document object.
EvioXMLDictionary(org.w3c.dom.Document domDocument, java.lang.String delimiter) Create an EvioXMLDictionary from an xml Document object.
EvioXMLDictionary(java.io.File file) Create an EvioXMLDictionary from an xml file.
EvioXMLDictionary(java.io.File file, java.lang.String delimiter) Create an EvioXMLDictionary from an xml file.
EvioXMLDictionary(java.lang.String xmlString) Create an EvioXMLDictionary from an xml string.
EvioXMLDictionary(java.lang.String xmlString, java.lang.String delimiter) Create an EvioXMLDictionary from an xml string.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getDescription(java.lang.Integer tag, java.lang.Integer num) Returns the description, if any, associated with the given tag and num.
java.lang.String	getDescription(java.lang.Integer tag, java.lang.Integer num, java.lang.Integer tagEnd) Returns the description, if any, associated with the given tag, num, and tagEnd.
java.lang.String	getDescription(java.lang.String name) Returns the description, if any, associated with the name of a dictionary entry.
java.lang.String	getFormat(java.lang.Integer tag, java.lang.Integer num, java.lang.Integer tagEnd) Returns the format, if any, associated with the given tag, num, and tagEnd.
java.lang.String	getFormat(int tag, int num) Returns the format, if any, associated with the given tag and num.
java.lang.String	getFormat(java.lang.String name) Returns the format, if any, associated with the name of a dictionary entry.
java.util.Map<java.lang.String,EvioDictionaryEntry>	getMap() Get the map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.).
java.lang.String	getName(BaseStructure structure) Returns the name of a given evio structure.
java.lang.String	getName(java.lang.Integer tag, java.lang.Integer num) Returns the name associated with the given tag, num, and tagEnd.
java.lang.String	getName(java.lang.Integer tag, java.lang.Integer num, java.lang.Integer tagEnd) Returns the name associated with the given tag, num, and tagEnd.
java.lang.String	getName(java.lang.Integer tag, java.lang.Integer num, java.lang.Integer tagEnd, java.lang.Integer pTag, java.lang.Integer pNum, java.lang.Integer pTagEnd) Returns the name associated with the given tag, num, and tagEnd.
java.lang.Integer	getNum(java.lang.String name) Returns the num corresponding to the name of a dictionary entry.
java.lang.Integer	getTag(java.lang.String name) Returns the tag corresponding to the name of a dictionary entry.
java.lang.Integer	getTagEnd(java.lang.String name) Returns the tagEnd corresponding to the name of a dictionary entry.
java.lang.Integer[]	getTagNum(java.lang.String name) Returns the tag/num/tagEnd values, in an Integer object array, corresponding to the name of a dictionary entry.
DataType	getType(java.lang.Integer tag, java.lang.Integer num) Returns the type, if any, associated with the given tag and num.
DataType	getType(java.lang.Integer tag, java.lang.Integer num, java.lang.Integer tagEnd) Returns the type, if any, associated with the given tag, num, and tagEnd.
DataType	getType(java.lang.String name) Returns the type, if any, associated with the name of a dictionary entry.
int	size() Get the number of entries in this dictionary.
java.lang.String	toString() Get a string representation of the dictionary.
java.lang.String	toXML() Get an xml representation of the dictionary.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

tagNumMap

public java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String> tagNumMap

This is the heart of the dictionary in which a key is composed of a tag/num pair and other entry data and its corresponding value is a name. Using a hashmap ensures entries are unique.

Since:

4.0

tagOnlyMap

public java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String> tagOnlyMap

Some dictionary entries have only a tag and no num. It matches a tag/num pair if there is no exact match in tagNumMap, but does match a tag in this map.

Since:

4.1

tagRangeMap

public java.util.LinkedHashMap<EvioDictionaryEntry,java.lang.String> tagRangeMap

Some dictionary entries have only a tag range and no num. It matches a tag/num pair if there is no exact match in tagNumMap or in the tagOnlyMap but the tag is within the specified range of an entry.

Since:

5.2

Constructor Detail

EvioXMLDictionary

public EvioXMLDictionary(java.io.File file)

Create an EvioXMLDictionary from an xml file.

Parameters:

file - file containing xml.

EvioXMLDictionary

public EvioXMLDictionary(java.io.File file,
                         java.lang.String delimiter)

Create an EvioXMLDictionary from an xml file.

Parameters:

file - file containing xml.

delimiter - character used to separate hierarchical parts of names.

EvioXMLDictionary

public EvioXMLDictionary(java.lang.String xmlString)

Create an EvioXMLDictionary from an xml string.

Parameters:

xmlString - string containing xml.

EvioXMLDictionary

public EvioXMLDictionary(java.lang.String xmlString,
                         java.lang.String delimiter)

Create an EvioXMLDictionary from an xml string.

Parameters:

xmlString - string containing xml.

delimiter - character used to separate hierarchical parts of names.

EvioXMLDictionary

public EvioXMLDictionary(org.w3c.dom.Document domDocument)

Create an EvioXMLDictionary from an xml Document object.

Parameters:

domDocument - DOM object representing xml dictionary.

EvioXMLDictionary

public EvioXMLDictionary(org.w3c.dom.Document domDocument,
                         java.lang.String delimiter)

Create an EvioXMLDictionary from an xml Document object.

Parameters:

domDocument - DOM object representing xml dictionary.

delimiter - character used to separate hierarchical parts of names.

Method Detail

size

public int size()

Get the number of entries in this dictionary.

Returns:

number of entries in this dictionary.

getMap

public java.util.Map<java.lang.String,EvioDictionaryEntry> getMap()

Get the map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.).

Returns:

map in which the key is the entry name and the value is an object containing its data (tag, num, type, etc.).

getName

public java.lang.String getName(BaseStructure structure)

Returns the name of a given evio structure. This is the method used in BaseStructure.toString() (and therefore also in JEventViewer), to assign a dictionary entry to a particular evio structure.

Specified by:

getName in interface INameProvider

Parameters:

structure - the structure to find the name of.

Returns:

a descriptive name or ??? if none found

getName

public java.lang.String getName(java.lang.Integer tag,
                                java.lang.Integer num)

Returns the name associated with the given tag, num, and tagEnd. If a valid tag and num are given (>= 0) a search is made for:

1. an entry of a tag/num pair. If that fails,
2. an entry of a tag only. If that fails,
3. an entry of a tag range.

If only a valid tag is given, a search is made for:

1. an entry of a tag only. If that fails,
2. an entry of a tag range.

All other argument values result in ??? being returned.

Parameters:

tag - tag of dictionary entry to find

num - num of dictionary entry to find

Returns:

descriptive name or ??? if none found

getName

public java.lang.String getName(java.lang.Integer tag,
                                java.lang.Integer num,
                                java.lang.Integer tagEnd,
                                java.lang.Integer pTag,
                                java.lang.Integer pNum,
                                java.lang.Integer pTagEnd)

Returns the name associated with the given tag, num, and tagEnd. If a valid tag and num are given (>= 0) a search is made for:

1. an entry of a tag/num pair. If that fails,
2. an entry of a tag only. If that fails,
3. an entry of a tag range.

If only a valid tag is given, a search is made for:

1. an entry of a tag only. If that fails,
2. an entry of a tag range.

If a valid tag range is given (different valid tag and tagEnd with no num), a search is made for an entry of a tag range. Note: tag and tagEnd being the same value or tagEnd being 0 mean that no range is defined - it's equivalent to only specifying a tag.

Argument values which have no match result in "???" being returned.

Things are actually more complicated due to parent structures. Duplicate entries (same tag, num, and tagEnd) are permitted only as long their parent entries are different. Say, for example, that this dictionary is defined as follows:

      <bank name="B1" tag="1" num="1" >
           <bank name="sub1" tag="5" num="5" />
           <bank name="sub2" tag="5" num="5" />
           <leaf name="tagNum"   tag="10" num="10" />
           <leaf name="tagOnly"  tag="20" />
           <leaf name="tagRange" tag="30-40" />
      </bank>
      <bank name="B2" tag="2" num="2" >
           <leaf name="tagNum"   tag="10" num="10" />
           <leaf name="tagOnly"  tag="20" />
           <leaf name="tagRange" tag="30-40" />
      </bank>

 

You can see that the leaf entries under bank "B1" are identical to those under "B2". This is permitted since B1 and B2 have different tag & num values so there is a way to tell the difference between the 2 instances of tagNum, tagOnly and tagRange.

It is not possible to specify parents using the "dictEntry" XML element and consequently duplicates are not allowed if using this form of dictionary definition. Think of things like this: no parents = no duplicates.

Parameters:

tag - tag of dictionary entry to find

num - num of dictionary entry to find

tagEnd - tagEnd of dictionary entry to find

pTag - tag of dictionary entry's parent

pNum - num of dictionary entry's parent

pTagEnd - tagEnd of dictionary entry's parent

Returns:

descriptive name or "???" if none found

getName

public java.lang.String getName(java.lang.Integer tag,
                                java.lang.Integer num,
                                java.lang.Integer tagEnd)

Returns the name associated with the given tag, num, and tagEnd. If a valid tag and num are given (>= 0) a search is made for:

1. an entry of a tag/num pair. If that fails,
2. an entry of a tag only. If that fails,
3. an entry of a tag range.

If only a valid tag is given, a search is made for:

1. an entry of a tag only. If that fails,
2. an entry of a tag range.

If a valid tag range is given (different valid tag and tagEnd with no num), a search is made for an entry of a tag range. Note: tag and tagEnd being the same value or tagEnd being 0 mean that no range is defined - it's equivalent to only specifying a tag.

All other argument values result in ??? being returned.

Parameters:

tag - tag of dictionary entry to find

num - num of dictionary entry to find

tagEnd - tagEnd of dictionary entry to find

Returns:

descriptive name or ??? if none found

getDescription

public java.lang.String getDescription(java.lang.Integer tag,
                                       java.lang.Integer num)

Returns the description, if any, associated with the given tag and num.

Parameters:

tag - to find the description of

num - to find the description of

Returns:

description or null if none found

getDescription

public java.lang.String getDescription(java.lang.Integer tag,
                                       java.lang.Integer num,
                                       java.lang.Integer tagEnd)

Returns the description, if any, associated with the given tag, num, and tagEnd.

Parameters:

tag - to find the description of

num - to find the description of

tagEnd - to find the description of

Returns:

description or null if none found

getDescription

public java.lang.String getDescription(java.lang.String name)

Returns the description, if any, associated with the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

description; null if name or is unknown or no description is associated with it

getFormat

public java.lang.String getFormat(int tag,
                                  int num)

Returns the format, if any, associated with the given tag and num.

Parameters:

tag - to find the format of

num - to find the format of

Returns:

the format or null if none found

getFormat

public java.lang.String getFormat(java.lang.Integer tag,
                                  java.lang.Integer num,
                                  java.lang.Integer tagEnd)

Returns the format, if any, associated with the given tag, num, and tagEnd.

Parameters:

tag - to find the format of

num - to find the format of

tagEnd - to find the format of

Returns:

format or null if none found

getFormat

public java.lang.String getFormat(java.lang.String name)

Returns the format, if any, associated with the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

format; null if name or is unknown or no format is associated with it

getType

public DataType getType(java.lang.Integer tag,
                        java.lang.Integer num)

Returns the type, if any, associated with the given tag and num.

Parameters:

tag - to find the type of

num - to find the type of

Returns:

type or null if none found

getType

public DataType getType(java.lang.Integer tag,
                        java.lang.Integer num,
                        java.lang.Integer tagEnd)

Returns the type, if any, associated with the given tag, num, and tagEnd.

Parameters:

tag - to find the type of

num - to find the type of

tagEnd - to find the type of

Returns:

type or null if none found

getType

public DataType getType(java.lang.String name)

Returns the type, if any, associated with the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

type; null if name or is unknown or no type is associated with it

getTagNum

public java.lang.Integer[] getTagNum(java.lang.String name)

Returns the tag/num/tagEnd values, in an Integer object array, corresponding to the name of a dictionary entry.

If there is an exact match with a tag and num pair, it is returned (last element is null). If not, but there is a match with a tag-only entry, that is returned (last 2 elements are null). If no tag-only match exits, but there is a match with a tag range, that is returned (i.e. second element, the num, is null).

Parameters:

name - dictionary name

Returns:

an Integer object array in which the first element is the tag, the second is the num, and the third is the end of a tag range; null if name is unknown

Since:

5.2 now returns 3 Integer objects instead of 2 ints (tag, num) as in previous versions.

getTag

public java.lang.Integer getTag(java.lang.String name)

Returns the tag corresponding to the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

tag or null if name unknown

getTagEnd

public java.lang.Integer getTagEnd(java.lang.String name)

Returns the tagEnd corresponding to the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

tagEnd or null if name unknown

getNum

public java.lang.Integer getNum(java.lang.String name)

Returns the num corresponding to the name of a dictionary entry.

Parameters:

name - dictionary name

Returns:

num or null if name unknown

toXML

public java.lang.String toXML()

Get an xml representation of the dictionary.

Returns:

an xml representation of the dictionary.

toString

public java.lang.String toString()

Get a string representation of the dictionary.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the dictionary.