pds.label
Class PDSLabel

java.lang.Object
  |
  +--pds.label.PDSLabel

public class PDSLabel
extends java.lang.Object

PDSLabel is a class that contians all information regarding a PDS label entity. A PDS label entity consists of one or more elements as specified in the PDS Object Defnition Language (ODL). Each element may be a simple line of text, a block of commented text, or a keyword/value pair. Comments and values may extend over more than one physical line.

Since:
1.0

Field Summary
 java.util.ArrayList mElement
          The list of elements in the label
 java.lang.String mPathName
          The path and file name used when loading a label from a file.
 
Constructor Summary
PDSLabel()
          Creates an instance of a PDSLabel
 
Method Summary
 void add(pds.label.PDSElement element)
          Add an element to the end of a label.
 void add(pds.label.PDSLabel label)
          Add a label to the end of a label.
 pds.label.PDSLabel extract(pds.label.PDSItem item)
          Extract a portion of a label into a new instance of label.
 java.util.ArrayList filePointers()
          Search the label and return a list to all points to files.
 pds.label.PDSItem findElement(java.lang.String name)
          Find the element with the given name.
 pds.label.PDSItem findElement(java.lang.String name, int startAt, int endAt)
          Find the element with the given name constrained to some portion of the label.
 pds.label.PDSItem findElement(java.lang.String name, pds.label.PDSItem item)
          Find the element with the given name constrained to some portion of the label.
 pds.label.PDSItem findNextElement(java.lang.String name, pds.label.PDSItem item)
          Find the next element with the given name starting at some point within the label.
 pds.label.PDSItem findObject(java.lang.String name)
          Find the object with the given name.
 pds.label.PDSItem findObject(java.lang.String name, int startAt, int endAt)
          Find the object with the given name within a partion of a label.
 pds.label.PDSItem findObject(java.lang.String name, pds.label.PDSItem item)
          Find the object with the given name within a partion of a label.
 pds.label.PDSElement getElement(pds.label.PDSItem item)
          Return the element data associated with an item.
 java.lang.String getElementValue(java.lang.String name)
          Find the value assocated with an element with the given name.
 void insertAfter(pds.label.PDSItem item, pds.label.PDSElement element)
          Insert an element after another element in this label.
 void insertAfter(pds.label.PDSItem item, pds.label.PDSLabel label)
          Insert a label after another element in this label.
 void insertBefore(pds.label.PDSItem item, pds.label.PDSElement element)
          Insert an element before another element in this label.
 void insertBefore(pds.label.PDSItem item, pds.label.PDSLabel label)
          Insert a label before another element in this label.
 boolean isLabel(java.lang.String pathName)
          Determines if a file contains a PDS label.
 pds.label.PDSItem nextElement(pds.label.PDSItem item)
          Find the next element after the given item.
 boolean parse(java.io.FileInputStream file)
          Parses a file containing a PDS label into its constitute elments.
 boolean parse(java.lang.String pathName)
          Parses a file containing a PDS label into its constitute elments.
 java.lang.String path()
          Returns the path portion of the fully qualified name of the file which was parsed.
 void print()
          Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.
 void print(java.io.PrintStream out)
          Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.
 void print(java.io.PrintStream out, int indent, int equal)
          Print all elements in the label according to PDS specifications for label files.
 void print(java.io.PrintStream out, int indent, int equal, int startAt, int endAt)
          Print a range of elements in the label according to PDS specifications for label files.
 void print(java.io.PrintStream out, int indent, int equal, pds.label.PDSItem item)
          Print a range of elements in the label according to PDS specifications for label files.
 void print(java.lang.String pathName)
          Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.
 void print(java.lang.String pathName, int indent, int equal)
          Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.
 void remove(pds.label.PDSItem item)
          Remove a range of elements from the label.
 void replace(pds.label.PDSItem item, pds.label.PDSLabel label)
          Replace an item in a label with another label.
 void reset()
          Reset all internal variables to the initial state.
 java.lang.String version()
          Returns a string with the release information for this compilation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mElement

public java.util.ArrayList mElement
The list of elements in the label


mPathName

public java.lang.String mPathName
The path and file name used when loading a label from a file.

Constructor Detail

PDSLabel

public PDSLabel()
Creates an instance of a PDSLabel

Method Detail

version

public java.lang.String version()
Returns a string with the release information for this compilation.

Returns:
a string contining the release information for this compilation.
Since:
1.0

reset

public void reset()
Reset all internal variables to the initial state.

Since:
1.0

isLabel

public boolean isLabel(java.lang.String pathName)
Determines if a file contains a PDS label. If the first 14 characters are either "PDS_VERSION_ID" or "CCSD3ZF0000100" then the file is considered to contain a PDS label.

Parameters:
pathName - the fully qualified path and name of the file to parse.
Returns:
true if the file contains a label. false otherwise.
Since:
1.0

parse

public boolean parse(java.lang.String pathName)
Parses a file containing a PDS label into its constitute elments. The path and name of the file are passed to the method which is opened and parsed.

Parameters:
pathName - the fully qualified path and name of the file to parse.
Returns:
true if the file could be opened; false otherwise.
Since:
1.0

parse

public boolean parse(java.io.FileInputStream file)
Parses a file containing a PDS label into its constitute elments. The file to parse must be previously opened and a FileInputStream pointing to the file is passed.

Parameters:
file - a connection to a pre-opened file.
Returns:
true if the file could be read; false otherwise.
Since:
1.0

path

public java.lang.String path()
Returns the path portion of the fully qualified name of the file which was parsed.

Returns:
the path to the file most recently parsed. The returned value will be blank if no file has been parsed or if a FileInputStream was used when parsing the file.
Since:
1.0

findObject

public pds.label.PDSItem findObject(java.lang.String name)
Find the object with the given name. Looks for elements with the keyword "OBJECT" and a value of the given name. If such an element is found then the corresponding element with the keyword "END_OBJECT" is located. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. The search begins at the first element in the label and extends to the last.

Parameters:
name - the name of the object to find. This can contain regular expressions.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

findObject

public pds.label.PDSItem findObject(java.lang.String name,
                                    pds.label.PDSItem item)
Find the object with the given name within a partion of a label. Looks for elements with the keyword "OBJECT" and a value of the given name. If such an element is found then the corresponding element with the keyword "END_OBJECT" is located. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. The search begins at the first element indicated the PDSItem and extends to the last.

Parameters:
name - the name of the element to find. This can contain regular expressions.
item - the item the search is to constrained within. If item is null then the search will span the entire label.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

findObject

public pds.label.PDSItem findObject(java.lang.String name,
                                    int startAt,
                                    int endAt)
Find the object with the given name within a partion of a label. Looks for elements with the keyword "OBJECT" and a value of the given name. If such an element is found then the corresponding element with the keyword "END_OBJECT" is located. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. The search begins at the element at the startAt position in the list and extends to the element at the endAt position.

Parameters:
name - the name of the element to find. This can contain regular expressions.
startAt - the index of the element at which to start the search.
endAt - the index of the element at which to end the search.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

getElementValue

public java.lang.String getElementValue(java.lang.String name)
Find the value assocated with an element with the given name. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. Also any occurance of "^" is converted to a literal "^" since it is a valid character in keywords. The search begins at the first element in the label and extends to the last.

Parameters:
name - the name of the element to find. This can contain regular expressions.
Returns:
a String containing the first value associated with the named element. If the element was not found the value returned is empty.
Since:
1.0

findElement

public pds.label.PDSItem findElement(java.lang.String name)
Find the element with the given name. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. Also any occurance of "^" is converted to a literal "^" since it is a valid character in keywords. The search begins at the first element in the label and extends to the last.

Parameters:
name - the name of the element to find. This can contain regular expressions.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

findElement

public pds.label.PDSItem findElement(java.lang.String name,
                                     pds.label.PDSItem item)
Find the element with the given name constrained to some portion of the label. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. Also any occurance of "^" is converted to a literal "^" since it is a valid character in keywords. The search begins at the first element indicated in the passed PDSItem and extends to the last item.

Parameters:
name - the name of the element to find. This can contain regular expressions.
item - a PDSItem to limit the search within. If item is null then search the entire label.
Returns:
a PDSItem that indicates the location of the element within the label.
Since:
1.0

findElement

public pds.label.PDSItem findElement(java.lang.String name,
                                     int startAt,
                                     int endAt)
Find the element with the given name constrained to some portion of the label. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. Also any occurance of "^" is converted to a literal "^" since it is a valid character in keywords. The search begins at the first element indicated in the passed PDSItem and extends to the last item.

Parameters:
name - the name of the element to find. This can contain regular expressions.
startAt - the index of the element to begin the search. If startAt is -1 then search from the beginning of the label.
endAt - the index of the element to end the search. If endAt is -1 then search to the end of the label.
Returns:
a PDSItem that indicates the location of the element within the label.
Since:
1.0

findNextElement

public pds.label.PDSItem findNextElement(java.lang.String name,
                                         pds.label.PDSItem item)
Find the next element with the given name starting at some point within the label. The passed name can contain regular expressions. Any occurance of a "*" in the string is converted to the regular expression ".*" to match any number of characters. Also any occurance of "^" is converted to a literal "^" since it is a valid character in keywords. The search begins at the first element indicated in the passed PDSItem and extends to the end of the label.

Parameters:
name - the name of the element to find. This can contain regular expressions.
item - a PDSItem indicating where to begin the search.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

nextElement

public pds.label.PDSItem nextElement(pds.label.PDSItem item)
Find the next element after the given item.

Parameters:
item - a PDSItem indicating where to begin the search.
Returns:
a PDSItem the indicates the start and end of the object within the label.
Since:
1.0

getElement

public pds.label.PDSElement getElement(pds.label.PDSItem item)
Return the element data associated with an item.

Parameters:
item - a PDSItem to return the element data for. The data associated with the first element of the item is returned.
Returns:
a PDSElement associated witht he first element of the item. the label. If no element is associated with the item null is returned.
Since:
1.0

replace

public void replace(pds.label.PDSItem item,
                    pds.label.PDSLabel label)
Replace an item in a label with another label.

Parameters:
item - a PDSItem indicating the elements to replace.
label - the label to place where item is currently.
Since:
1.0

add

public void add(pds.label.PDSElement element)
Add an element to the end of a label.

Parameters:
element - the element to add to the end of the label.
Since:
1.0

add

public void add(pds.label.PDSLabel label)
Add a label to the end of a label.

Parameters:
label - the label to add to the end of the label.
Since:
1.0

insertBefore

public void insertBefore(pds.label.PDSItem item,
                         pds.label.PDSLabel label)
Insert a label before another element in this label. If the element location is invalid nothing is done.

Parameters:
item - the location of the element before which the label is inserted.
label - the label to place before the passed item.
Since:
1.0

insertAfter

public void insertAfter(pds.label.PDSItem item,
                        pds.label.PDSLabel label)
Insert a label after another element in this label. If the location of the element is passed the end of this label the label is appended to this label. If the element location is invalid nothing is done.

Parameters:
item - the location of the element after which the label is inserted.
label - the label to place after the passed item.
Since:
1.0

insertBefore

public void insertBefore(pds.label.PDSItem item,
                         pds.label.PDSElement element)
Insert an element before another element in this label. If the element location is invalid nothing is done.

Parameters:
item - the location of the element before which the element is inserted.
element - the element to place before the passed item.
Since:
1.0

insertAfter

public void insertAfter(pds.label.PDSItem item,
                        pds.label.PDSElement element)
Insert an element after another element in this label. If the location of the element is passed the end of this label the label is appended to this label. If the element location is invalid nothing is done.

Parameters:
item - the location of the element after which the element is inserted.
element - the element to place after the passed item.
Since:
1.0

remove

public void remove(pds.label.PDSItem item)
Remove a range of elements from the label. If the range of elements in the passed item is invalid nothing is done.

Parameters:
item - the location of the elements to remove.
Since:
1.0

extract

public pds.label.PDSLabel extract(pds.label.PDSItem item)
Extract a portion of a label into a new instance of label. The range of elements to extract is given in a PDSItem

Parameters:
item - the location of the elements to extract.
Since:
1.0

filePointers

public java.util.ArrayList filePointers()
Search the label and return a list to all points to files. A pointer to a file is defined as any pointer keyword with a quoted value.

Returns:
a list of file names pointed to within the label. The list is in the form of an ArrayList of String objects. If no pointers are found then null is returned.
Since:
1.0

print

public void print()
Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.

Since:
1.0

print

public void print(java.lang.String pathName)
Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.

Parameters:
pathName - the path and name of the file to write the output to.
Since:
1.0

print

public void print(java.lang.String pathName,
                  int indent,
                  int equal)
Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.

Parameters:
pathName - the path and name of the file to write the output to.
indent - the number of spaces to indent each line at each level.
equal - the position to align equal signs following keywords.
Since:
1.0

print

public void print(java.io.PrintStream out)
Print all elements in the label according to PDS specifications for label files using default indent and equal sign placement.

Parameters:
out - the stream to print the element to.
Since:
1.0

print

public void print(java.io.PrintStream out,
                  int indent,
                  int equal)
Print all elements in the label according to PDS specifications for label files. Each line that is output can be indented with the equal sign (when present) placed at a fixed position. Output printed to System.out. Each occurance of an OBJECT is indented on level.

Parameters:
out - the stream to print the element to.
indent - the number of spaces to indent for each level.
equal - the number of spaces from the end of the indent to align the equal sign for elements which have a keyword and value.
Since:
1.0

print

public void print(java.io.PrintStream out,
                  int indent,
                  int equal,
                  pds.label.PDSItem item)
Print a range of elements in the label according to PDS specifications for label files. Each line that is output can be indented with the equal sign (when present) placed at a fixed position. Output printed to System.out. Each occurance of an OBJECT is indented on level.

Parameters:
out - the stream to print the element to.
indent - the number of spaces to indent for each level.
equal - the number of spaces from the end of the indent to align the equal sign for elements which have a keyword and value.
item - the item to output.
Since:
1.0

print

public void print(java.io.PrintStream out,
                  int indent,
                  int equal,
                  int startAt,
                  int endAt)
Print a range of elements in the label according to PDS specifications for label files. Each line that is output can be indented with the equal sign (when present) placed at a fixed position. Output printed to System.out. Each occurance of an OBJECT is indented on level.

Parameters:
out - the stream to print the element to.
indent - the number of spaces to indent for each level.
equal - the number of spaces from the end of the indent to align the equal sign for elements which have a keyword and value.
startAt - the first element to output.
endAt - the last element to output.
Since:
1.0