org.licas.parsers

## Class Parsers

- java.lang.Object
- - org.licas.parsers.Parsers

-     public class Parsers
      extends java.lang.Object

  The communication parsing goes through this class. It stores the appropriate parser to parse any of the registered data structures. This class initiates the parsing procedure to convert a Java object into XML or String and back again.

  There are a number of default parsers for standard Java objects, that this parser will load when it is initiated. These will parse a number of different list types, XML elements, or other standard objects. You can then add your own parser for any objects that you might pass as part of a communication process. The `addParser` method adds the parser here, in the form of the parser itself and the name of the class that it will parse. To add a parser to a remote server, you invoke the addParser method on the server instead. The parsing process will also try to Base64 serialize objects if there is no XML parser available and they have extended the Java `Serializable` interface.

  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.String` | `PARSE` Parser parse method
    `protected static java.lang.String` | `SERIALIZE` Parser serialize method

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Parsers()` Creates a new instance of Parsers

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `addParser(java.lang.String className, java.lang.Object parser)` Add a new parser to the list, but do not overwrite an existing parser for that class.
    `static java.lang.Object` | `createObject(java.lang.String className, org.licas_xml.abs.Element xmlElem)` Create the object as specified by the element.
    `static java.lang.Object` | `createObject(java.lang.String className, java.lang.String value)` Create the object as specified by the string.
    `static void` | `createParameterElement(java.lang.Object toSerialize, org.licas_xml.abs.Element rootElem)` Create a specific `Const`.`PARAMTER` element for the specified object.
    `static java.util.ArrayList` | `getParsedClasses()` Retrieve the list of classes that can be parsed by the parsers.
    `static org.ai_heuristic.def.ParserDef` | `getParser(java.lang.String classType)` Return a parser for the specified class type if one exists.
    `static boolean` | `hasParser(java.lang.String classType)` Return true if a parser for the specified class type exists.
    `static java.lang.Object` | `parse(org.licas_xml.abs.Element toParse)` If a parser is available for the object then convert the element back to the object.
    `static java.lang.Object` | `parse(java.lang.String toParse)` If a parser is available for the object then convert the String-based xml description of the element back to the object.
    `static java.lang.Object` | `parseObject(java.lang.Object toParse)` Parse an object representation back into the correct object.
    `static java.lang.Object` | `parseObject(java.lang.String className, java.lang.Object toParse)` Parse an object representation back into the correct object.
    `static java.lang.String` | `removeCoding(java.lang.String xmlStr)` Remove all element prefixes and extra coding to clean the string completely.
    `static boolean` | `removeParser(java.lang.String className)` Add a new parser to the list.
    `static org.licas_xml.abs.Element` | `serializeToElement(java.lang.Object toSerialize)` Convert the object into an xml Element if a parser exists.
    `static PacketInfo` | `serializeToFile(java.lang.Object toSerialize)` Convert the object into an xml-based description if a parser exists and save it to a file.
    `static java.lang.String` | `serializeToString(java.lang.Object toSerialize)` Convert the object into an xml String format if a parser exists.
    `static boolean` | `shouldConvert(java.lang.Class param, java.lang.Object obj)` Check if the second parameter is an XML element type that should be converted into an object.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PARSE

          protected static final java.lang.String PARSE

      Parser parse method
      See Also:
        Constant Field Values

    - #### SERIALIZE

          protected static final java.lang.String SERIALIZE

      Parser serialize method
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Parsers

          public Parsers()

      Creates a new instance of Parsers

  - ### Method Detail

    - #### hasParser

          public static boolean hasParser(java.lang.String classType)

      Return true if a parser for the specified class type exists.
      Parameters:
        `classType` - the class type of the object that needs parsing.
      Returns:
        true if a parser has been added for that class type, false otherwise.

    - #### addParser

          public static boolean addParser(java.lang.String className,
                                          java.lang.Object parser)

      Add a new parser to the list, but do not overwrite an existing parser for that class.
      Parameters:
        `className` - the class name of the object that the parser will parse.
        `parser` - the parser. Must implement ParserDef interface.
      Returns:
        true if the parser is added, false otherwise.

    - #### removeParser

          public static boolean removeParser(java.lang.String className)

      Add a new parser to the list.
      Parameters:
        `className` - the class name of the object to parse.
      Returns:
        true if the operation was OK.

    - #### getParser

          public static org.ai_heuristic.def.ParserDef getParser(java.lang.String classType)

      Return a parser for the specified class type if one exists.
      Parameters:
        `classType` - the class type of the object that needs parsing.
      Returns:
        a parser if one has been added for that class type, null otherwise.

    - #### parseObject

          public static java.lang.Object parseObject(java.lang.Object toParse)
                                              throws java.lang.Exception

      Parse an object representation back into the correct object. This adds another layer above the `parse` methods, before calling them. NOTE: The class type is assumed to be what the object itself is.
      Parameters:
        `toParse` - the object description to convert.
      Returns:
        a converted description, or the object itself if that was not possible.
      Throws:
        `java.lang.Exception` - any error.

    - #### parseObject

          public static java.lang.Object parseObject(java.lang.String className,
                                                     java.lang.Object toParse)
                                              throws java.lang.Exception

      Parse an object representation back into the correct object. This adds another layer above the `parse` methods, before calling them.
      Parameters:
        `className` - the object class name, in case different to the representation object.
        `toParse` - the object description to convert.
      Returns:
        a converted description, or the object itself if that was not possible.
      Throws:
        `java.lang.Exception` - any error.

    - #### parse

          public static java.lang.Object parse(java.lang.String toParse)
                                        throws java.lang.Exception

      If a parser is available for the object then convert the String-based xml description of the element back to the object. The process is to convert this into an Element and parse again, or de-serialize and return.
      Parameters:
        `toParse` - the object description to parse back.
      Returns:
        the original object, or null if `toParse` is null.
      Throws:
        `java.lang.Exception` - any error.

    - #### parse

          public static java.lang.Object parse(org.licas_xml.abs.Element toParse)
                                        throws java.lang.Exception

      If a parser is available for the object then convert the element back to the object. If no conversion type attribute, as part of a parameter description, then return the original toParse Element.
      Parameters:
        `toParse` - the object to parse back.
      Returns:
        the original object.
      Throws:
        `java.lang.Exception` - any error.

    - #### serializeToString

          public static java.lang.String serializeToString(java.lang.Object toSerialize)
                                                    throws java.lang.Exception

      Convert the object into an xml String format if a parser exists.
      Parameters:
        `toSerialize` - the object to convert.
      Returns:
        the object parsed into xml-based String.
      Throws:
        `java.lang.Exception` - any error.

    - #### serializeToElement

          public static org.licas_xml.abs.Element serializeToElement(java.lang.Object toSerialize)
                                                              throws java.lang.Exception

      Convert the object into an xml Element if a parser exists. If a String reply is serialized, then wrap that in a single element before returning.
      Parameters:
        `toSerialize` - the object to convert.
      Returns:
        the parsed object, wrapped in an xml `Element`.
      Throws:
        `java.lang.Exception` - any error.

    - #### serializeToFile

          public static PacketInfo serializeToFile(java.lang.Object toSerialize)
                                            throws java.lang.Exception

      Convert the object into an xml-based description if a parser exists and save it to a file. Create a `PacketInfo` object to represent the file.
      Parameters:
        `toSerialize` - the object to convert.
      Returns:
        the `PacketInfo` object with the information. This can then be read in parts, for example.
      Throws:
        `java.lang.Exception` - any error.

    - #### createParameterElement

          public static void createParameterElement(java.lang.Object toSerialize,
                                                    org.licas_xml.abs.Element rootElem)
                                             throws java.lang.Exception

      Create a specific `Const`.`PARAMTER` element for the specified object.
      Parameters:
        `toSerialize` - the object to parse.
        `rootElem` - root element, if the created element gets added to one.
      Throws:
        `java.lang.Exception` - any error.

    - #### createObject

          public static java.lang.Object createObject(java.lang.String className,
                                                      java.lang.String value)
                                               throws java.lang.Exception

      Create the object as specified by the string.
      Parameters:
        `className` - the object class name.
        `value` - the object value as a String-based description.
      Returns:
        the created object.
      Throws:
        `java.lang.Exception` - any error.

    - #### createObject

          public static java.lang.Object createObject(java.lang.String className,
                                                      org.licas_xml.abs.Element xmlElem)
                                               throws java.lang.Exception

      Create the object as specified by the element.
      Parameters:
        `className` - the object class name.
        `xmlElem` - root element if this stores the information and value is null.
      Returns:
        the created object.
      Throws:
        `java.lang.Exception` - any error.

    - #### shouldConvert

          public static boolean shouldConvert(java.lang.Class param,
                                              java.lang.Object obj)

      Check if the second parameter is an XML element type that should be converted into an object.
      Parameters:
        `param` - the first parameter class.
        `obj` - the second parameter object.
      Returns:
        true if should convert the parameter.

    - #### removeCoding

          public static java.lang.String removeCoding(java.lang.String xmlStr)

      Remove all element prefixes and extra coding to clean the string completely.
      Parameters:
        `xmlStr` - the string to remove prefixes from.
      Returns:
        the modified string.

    - #### getParsedClasses

          public static java.util.ArrayList getParsedClasses()

      Retrieve the list of classes that can be parsed by the parsers.
      Returns:
        the list of classes that can be parsed. Values are of type String.