pl.mbdev.openstage
Class Xml

java.lang.Object
  extended by pl.mbdev.openstage.Xml
Direct Known Subclasses:
Image, IppAction, IppAlert, IppCommand, IppDisplay, IppForm, IppHidden, IppItem, IppKey, IppList, IppPhone, IppPhoneNumber, IppScreen, IppTicker, Option, OptionText, XmlFormItem, XmlText, XmlWithKey

public abstract class Xml
extends java.lang.Object

General definition of an XML object that represents the common part of all XML entities used by OpenStage 60/80 VoIP phones, according to the "OpenStage 60/80 - XML Applications, Developer's Guide" available in September 2011.

 Copyright 2011 Mateusz Bysiek,
     mb@mbdev.pl, http://mbdev.pl/
 
 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
 
     http://www.apache.org/licenses/LICENSE-2.0
 
 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.
 

Author:
Mateusz Bysiek

Field Summary
private  java.lang.String contents
          Contents of this node.
private  Xml logicalRoot
          The node that is considered as a node with respect to which all operations are made.
private  java.lang.String nodeName
          Name of this object in its XML-text form.
private  Xml parent
          Parent of this node.
private  java.util.ArrayList<Xml> subObjects
          References to all sub-objects of this XML object.
 
Constructor Summary
private Xml()
          Parameterless constructor.
  Xml(java.lang.String nodeName)
          Default constructor.
  Xml(java.lang.String nodeName, java.lang.Object contents)
          Creates new node, without sub-nodes but with text contents.
 
Method Summary
protected  void add(java.lang.String nodeName, java.lang.Object contents)
          Adds a simple sub-node to this XML entity.
protected  Xml add(Xml o)
          Adds the provided XML object to sub-objects of this object, and returns it.
protected  Xml addAndReturn(java.lang.String nodeName, java.lang.Object contents)
          Adds a simple sub-node to this XML entity, and returns a reference to it.
protected  java.lang.StringBuffer attributesToXmlString()
          Should be overridden by classes that have some attributes.
protected  java.lang.String attributeToXml(java.lang.String attributeName, java.lang.Object attributeValue)
          Converts an attribute for an object to its XML-text representation.
protected  java.lang.StringBuffer firstAttributesToXmlString()
          Special method used by intermediate subclasses, which may desire to attach attributes to the object without need to override attirbutesToXmlString() method.
 java.lang.String getContents()
          Gets the contents of this node.
protected  Xml getLogicalRoot()
          Gets the logical root of this object.
protected  Xml getParent()
          Returns the parent node of this node, provided that this node is some other object's sub-node.
protected  Xml getSubNode(int index)
           
protected  int getSubNodeIndex(Xml o)
          Returns the index of the first occurrence of the specified element in sub-nodes list, or -1 if that list does not contain the element.
protected  java.util.ArrayList<Xml> getSubNodes()
          Returns reference to the list of sub-nodes of this object.
protected  java.lang.StringBuffer getXmlHeader()
          Returns default XML file header, needed for proper interpretation of the file contents by the OpenStage device.
private  void insert(Xml o)
          Inserts the provided object between this node and its parent.
 boolean isEmpty()
          Checks if this node has any contents or sub-nodes.
protected  void logicalAdd(Xml o)
          Adds the provided XML object to the logical root of this object.
private  void remove(Xml o)
          Removes selected item from the list of sub-nodes of this XML object.
 void sendTo(java.io.PrintWriter out)
          This method sends the XML to the receiving OpenStage device.
protected  void setContents(java.lang.String contents)
          Sets the contents of this node.
protected  void setParent(Xml o)
          Sets parent of this object to a desired one.
protected  int subObjectsCount()
          Returns number of sub-nodes of this XML node.
protected  java.lang.StringBuffer subObjectsToXmlString(int indent)
          Goes through every sub-object of this object, creates its XML-text representation, and returns all of them in a single StringBuffer.
protected  java.lang.StringBuffer toXmlString(int indent)
          Returns full XML-text representation of this object, with all objects it contains inside, attributes, and a XML header.
protected  IppItem wrapWithIppItem()
          Wraps this XML object with a new IppItem and returns this IppItem.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

nodeName

private java.lang.String nodeName
Name of this object in its XML-text form.


contents

private java.lang.String contents
Contents of this node.


subObjects

private java.util.ArrayList<Xml> subObjects
References to all sub-objects of this XML object.


parent

private Xml parent
Parent of this node. May be null. Used in some cases when adding command to an item that should not usually have commands.


logicalRoot

private Xml logicalRoot
The node that is considered as a node with respect to which all operations are made.

Constructor Detail

Xml

private Xml()
Parameterless constructor.


Xml

public Xml(java.lang.String nodeName)
Default constructor. Creates new node without sub-nodes, and without any text contents.

Parameters:
nodeName - name of the XML node

Xml

public Xml(java.lang.String nodeName,
           java.lang.Object contents)
Creates new node, without sub-nodes but with text contents.

Parameters:
nodeName - name of the XML node
contents - contents of the XML entity
Method Detail

getSubNode

protected Xml getSubNode(int index)
Parameters:
index - non-negative number
Returns:
sub node at given index in the list of sub-nodes

getSubNodeIndex

protected int getSubNodeIndex(Xml o)
Returns the index of the first occurrence of the specified element in sub-nodes list, or -1 if that list does not contain the element. More formally, returns the lowest index i such that (o==null ? subObjects.get(i)==null : o.equals(subObjects.get(i))), or -1 if there is no such index.

Parameters:
o - element to search for
Returns:
the index of the first occurrence of the element in sub-nodes list, or -1 if the list does not contain the element specified

getSubNodes

protected java.util.ArrayList<Xml> getSubNodes()
Returns reference to the list of sub-nodes of this object.

Returns:
reference to the list of sub-nodes of this object

getParent

protected Xml getParent()
Returns the parent node of this node, provided that this node is some other object's sub-node.

Returns:
parent node of this node, null if it is a root node (has no parent)

getLogicalRoot

protected Xml getLogicalRoot()
Gets the logical root of this object.

Returns:
logical root of this object

setParent

protected void setParent(Xml o)
Sets parent of this object to a desired one.

Parameters:
o - any kind of XML object from OpenStage SDK

insert

private void insert(Xml o)
Inserts the provided object between this node and its parent.

Parameters:
o - any kind of XML object from OpenStage SDK

add

protected Xml add(Xml o)
Adds the provided XML object to sub-objects of this object, and returns it.

Parameters:
o - any kind of XML object from OpenStage SDK
Returns:
the object provided in the parameter

logicalAdd

protected void logicalAdd(Xml o)
Adds the provided XML object to the logical root of this object. In 99% of cases, you should use ordinary add() method instead of this one.

See description of logicalRoot attribute of Xml class for details like: what is a logical root, how to use it and how it is used by OpenStage SDK.

Parameters:
o - any kind of XML object from OpenStage SDK

remove

private void remove(Xml o)
Removes selected item from the list of sub-nodes of this XML object.

Parameters:
o - any kind of XML object from OpenStage SDK, that you wish to be removed

add

protected void add(java.lang.String nodeName,
                   java.lang.Object contents)
Adds a simple sub-node to this XML entity.

Parameters:
nodeName - name of the node
contents - contents, which will be converted to String

addAndReturn

protected Xml addAndReturn(java.lang.String nodeName,
                           java.lang.Object contents)
Adds a simple sub-node to this XML entity, and returns a reference to it.

Parameters:
nodeName - name of the node
contents - contents, which will be converted to String
Returns:
the added sub-node

wrapWithIppItem

protected IppItem wrapWithIppItem()
Wraps this XML object with a new IppItem and returns this IppItem. In case this object is already wrapped, it simply returns the existing IppItem that wraps the object.

Returns:
the IppItem

subObjectsCount

protected int subObjectsCount()
Returns number of sub-nodes of this XML node.

Returns:
nonnegative integer, number of sub-nodes of this XML node

firstAttributesToXmlString

protected java.lang.StringBuffer firstAttributesToXmlString()
Special method used by intermediate subclasses, which may desire to attach attributes to the object without need to override attirbutesToXmlString() method.

Returns:
should return attributes of the intermediate subclass in a XML-text format

attributesToXmlString

protected java.lang.StringBuffer attributesToXmlString()
Should be overridden by classes that have some attributes.

Returns:
XML-text containing all attributes of the object

attributeToXml

protected java.lang.String attributeToXml(java.lang.String attributeName,
                                          java.lang.Object attributeValue)
Converts an attribute for an object to its XML-text representation.

Parameters:
attributeName - name of the attribute
attributeValue - value of the attribute
Returns:
XML-text in the format: ' "name"="value"'

subObjectsToXmlString

protected java.lang.StringBuffer subObjectsToXmlString(int indent)
Goes through every sub-object of this object, creates its XML-text representation, and returns all of them in a single StringBuffer.

Parameters:
indent - indent of the output of this function, done by tab character
Returns:
XML-text with all sub-objects of this object

toXmlString

protected java.lang.StringBuffer toXmlString(int indent)
Returns full XML-text representation of this object, with all objects it contains inside, attributes, and a XML header.

Parameters:
indent - indent of the output of this function, done by tab character
Returns:
full XML-text representation of this object

isEmpty

public boolean isEmpty()
Checks if this node has any contents or sub-nodes.

Returns:
true if this node does not have any contents or sub-nodes

getXmlHeader

protected java.lang.StringBuffer getXmlHeader()
Returns default XML file header, needed for proper interpretation of the file contents by the OpenStage device.

Returns:
default XML file header, needed for proper interpretation of the file contents by the OpenStage device

sendTo

public void sendTo(java.io.PrintWriter out)
            throws java.lang.IllegalArgumentException
This method sends the XML to the receiving OpenStage device.

Parameters:
out - stream that receives sent content
Throws:
java.lang.IllegalArgumentException - when the server is trying to send an object that cannot be a root or cannot be "made" a root

getContents

public java.lang.String getContents()
Gets the contents of this node.

Returns:
the contents of this node

setContents

protected void setContents(java.lang.String contents)
Sets the contents of this node.

Parameters:
contents - new contents of this node