PlainiXML is Open Source project. It is licensed 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 Apache License 2.0 license. 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.

At least Java5 Standard Edition is required to compile and use PlainXML.

The following methods should be overriden in classes inherited from XMLElement (in other words, in ones which correspond to specific XML element):

  // attributes registration
  protected void init();
  // returns meta-type for XML element
  //(ones should be unique within a scheme)
  public int Type();
  // type of element content - may be one of
  // EMPTY, ANY, CONTAINER
  public int ContentType();
  // returns DTD information for XML element
  public String GetDTDInfo();
   // returns name of XML element (name of tag)
  public String ElementName();
  // returns name of scheme which XML element
  // belongs to
  public String getSchemaID();
  public Object clone();
  // creates new instance of particular
  // XMLElement
  public static XMLElement newInstance();

The following basic types of XML attributes are supported:

  java.lang.String,
  boolean,
  int,
  double (number separator in xml is "."),
  java.util.Date (in formats "M/dd/yyyy",
                  "M/dd/yyyy HH:mm:ss Z"
                  and "HH:mm:ss Z")

  public static final String ATTR_XXX = "";
  ....
  public String getXXX(){
    return getAttrValue(ATTR_XXX);
  }
  public void setXXX(String aValue){
    setAttrValue(ATTR_XXX, aValue);
  }

  public static final String ATTR_YYY = "xxx";
  ....
  public int getXXX(){
     return getAttrValueAsInt(ATTR_YYY, Integer.MIN_VALUE);
  }
  public int getXXX(int aDefaultValue){
     return getAttrValueAsInt(ATTR_YYY, aDefaultValue);
  }
  public void setXXX(int aValue){
    if (aValue != Integer.MIN_VALUE)
      setAttrValueAsInt(ATTR_YYY, aValue);
    else
     setAttrValue(ATTR_YYY, null);
  }

  public static final String ATTR_ZZZ = "xxx";
  ....
  public double getXXX(){
     // 3 is amount of digits after
     // dot 
     return getAttrValueAsNumber(ATTR_ZZZ, 3, Double.NaN);
  }
  public double getXXX(double aDefaultValue){
    return getAttrValueAsNumber(ATTR_ZZZ, 3, aDefaultValue);
  }
  public void setXXX(double aValue){
    if (Double.isNaN(aValue))
      setAttrValue(ATTR_ZZZ, null);
    else
      setAttrValueAsNumber(ATTR_ZZZ, aValue, 3);
  }

  public static final String ATTR_DDD = "xxx";
  ....
  public Date getXXX(){
    return getAttrValueAsDate(ATTR_DDD, null);
  }
  public void setXXX(String aValue){
     if (aValue != null)
       setAttrValueAsDate(ATTR_DDD, aValue);
     else
       setAttrValue(ATTR_DDD, null);   
  }

  public static final String ATTR_BBB = "bbb";
  ....
  public boolean isXXX(){
    return isAttrValueYes(ATTR_BBB);
  }
  public void setXXX(Boolean aValue){
    if (aValue != null)
          setAttrValueAsBoolean(ATTR_BBB, aValue);
        else
          setAttrValue(ATTR_BBB, null);
  }

  this.getAttrValue(Attr_XXX)

  // or it's possible to check
  // whether attribute value is
  // "yes" or "no" 
  this.isAttrValueYes(Attr_XXX);
  this.isAttrValueNo(Attr_XXX);

The internal structure of XMLElement is quite flexible and allows to dynamicall add even unknown attributes and elements. This allows to have very convenient mechanism in algorythms which perfom various manipulation with XML - for example, one part of algoritym may add additional information to XML element via their attributes (either as some processing hints or data to process ) which will be passed along with XMLElement instance to further processing. Adding new "unregistered" attributed to XML element is pretty simple and could be done in the way illustrated below:

  // "true" parameter indicates
  // that if element was not
  // registered, it should be
  // added dynamically
  this.setAttrValue(Attr_Name, Attr_Value, true);

PCDATA value which is stored in XML element may be accessed by the following methods (please note that base64binary is also supported and that CDATA encoding is also supported).

  // obtaining PCDATA
  String val = this.getPCData();

  // setting PCDATA value
  // Last parameters indicates whether PCDATA
  // should be encoded as CDATA
  this.setPCData(val, true);

  // obtaining PCDATA
  // as Base64 binary
  byte[] base64 = this.getBase64Binary();

  public XmlObjXXX getFirstObjXXX(){
    XmlObjXXX result = null;
    int index = findFirst(XmlObjXXX.TYPE_ID);
    if (index != -1)
      result = (XmlObjXXX) Items().get(index);
    return result;
   }
   public XmlObjXXX getLastObjXXX(){
     XmlObjXXX result = null;
     int index = findLast(XmlObjXXX.TYPE_ID);
     if (index != -1)
       result = (XmlObjXXX) Items().get(index);
     return result;
   }
   public Iterable<XmlObjXXX> getAllObjXXXs(){
     return new ItemIterable<XmlObjXXX>(XmlObjXXX.TYPE_ID);
   }

  public XmlSomeObject getSomeObject(){
    XmlSomeObject result = null;
    int index = findFirst(XmlSomeObject.TYPE_ID);
    if (index != -1)
      result = (XmlSomeObject) Items().get(index);
    return result;
  }
  public void setSomeObject(XmlSomeObjectl elm){
    setFirstItem(XmlSomeObject.TYPE_ID, elm);
  }

It is possible to create ListIterator which will return only specific XML elements:

  ListIterator<XMLElement> itr =
     new ItemItr<XMLElement>(new AcceptBy("xxx"));    
  

Child XML elements with specific type could be removed from XML element as it's shown by code below:

  ListIterator<XMLElement> itr =
    new ItemItr<XMLElement>(new AcceptBy("xxx"));
  while(itr.hasNext()){
    XMLElement elm = itr.next();
    String attrValue = elm.getAttrValue("yyy");
    if ("zzz".equals(attrValue)){
       itr.remove();
    }
  }

Child XML elements could be directly accessed via appropriate property:

    List<XMLElement> items = this.Items();

The following code snippet illustrates select child XML elements by pattern and iterate over them.

    // either using iterator ...
    IElementAcceptor acceptor =
      new AcceptBy("abc*", "*efg", null);
    ListIterator<XMLElement> itr =
      new ItemItr<XMLElement>(acceptor);
    while(itr.hasNext()){
      XMLElement elm = itr.next();
           ....
    }
    // ... or using iterable
    IElementAcceptor acceptor =
      new AcceptBy("abc*", "*efg");
    Iterable<XMLElement> itr =
      new ItemIterable<XMLElement>(acceptor);
    for (XMLElement elm: itr){
            ...
    }

Child xml elements could be sorted by the following code.

  List<XMLElement> items = this.Items();
  Collections.sort(items, new CompareBy("yyy"));

Yes, it's possible to specify wildcard expression as attribute of method. The following types of wildcards are supported:

xxx*	String which starts from "xxx"
*xxx*	String which contains "xxx"
*xxx	String whih ends with "xxx"
xxx	Exact match

The following example illustrates how copy values of attributes from one XML element to another one.

  XmlSomeObj src ....;
  XmlSomeObj dest = XmlSomeObj.newInstance();
    
  // true indicates that child
  // elements should be copied
  // too (as shallow copy)
  dest.assignFrom(src, true);

Your code may be notified about changes in element structure of attributes if the following methods are overriden:

   protected boolean acceptAddChild(XMLElement aElement);
   protected boolean acceptChangeAttrValue(String aAttName,
             String aOldValue, String aNewValue);
   protected boolean acceptRemoveChild(XMLElement aElement);

The following code snippet illustrates how to restore DTD definition by existing XML element.

   XMLElementInfo elmInfo = new XMLElementInfo(aXMLElement);
   String dtdInfo = elmInfo.toText();

The following code snippet illustrates how to read POJO XML tree from file.

    FileInputStream  fis = new FileInputStream(aFile);
    if (fis != null){
      InputStreamReader isr =
        new InputStreamReader(fis, "UTF-8");
      Reader reader = new BufferedReader(isr);
      XMLReader docHandler = new XXXReader();
      try{
        XMLParser.parse(docHandler, reader);
        // XmlXXX - root for schema XXX
        root = (XmlXXXRoot) docHandler.getRoot();
      }
      finally{
         docHandler.clear();
      }
      //close IO resources
      ...
     }

The following example illustrates how to write POJO objects to binary XML format.

    ObjectOutput oos = new ObjectOutputStream(...);
    // xmlData contains root of
    // xml tree and is used for
    // custom XML marshalling/unmarshalling
    // using binary or plain format
    XMLData xmlData = new XMLData();
    xmlData.setRoot(aRootXmlElement);
    // Write to binary XML format
    xmlData.writeExternal(oos);

The following example illustrates how to read POJO objects from binary XML format.

    ObjectInput ois = new ObjectInputStream(...);
    // xmlData contains root of
    // xml tree and is used for
    // custom XML marshalling/unmarshalling
    // using binary or plain format
    XMLData xmlData = new XMLData();
    // Read from binary XML format
    xmlData.readExternal(ois);
    XMLElement root = xmlData.getRoot();

The following example illustrates how to write XML tree to JSON (JavaScript Object Notation).

    OutputStreamWriter osw = new OutputStreamWriter(os);
    Writer wout = new BufferedWriter(osw);
    // Here we create JSONWriter
    JSONWriter json = new JSONWriter();

    // And specify settings
    // which control output details,
    // if necessary
    json.setUseDTDInfo(true);
    json.setUsePrettyPrint(false);
    json.setSkipNotAssigned(true);
    json.setCheckAttrType(true);

    // Also, if necessary,
    // we could specify element
    // names substitution map
    json.replaceElementName("var", "macro");

    // And finally, here
    // we initiate export
    json.write(wout, journal);

Let us know it! Please submit bugs and feature ideas or patches to the email [email protected], and we’ll get on it.

Please do not hesitate contacting us if you have any questions, comments, suggestions or simply find some issues with PlainXML. Please send us your feedback via email using [email protected] email addresss.