jcs.xml.order
Class OrderXml

java.lang.Object
  |
  +--jcs.xml.JXml
        |
        +--jcs.xml.order.OrderXml

public class OrderXml
extends JXml
implements java.io.Serializable

A subclass of the JXml class, for the "Order" DTD. This subclass validates the documents with the Order DTD. The "Order" DTD is a simple example DTD for purchase-order type data.

See Also:
Serialized Form

Fields inherited from class jcs.xml.JXml
xmlText
 
Constructor Summary
OrderXml(java.lang.String orderXmlText)
          A constructor whose parameter is a String containing a valid XML "Order" document.
OrderXml(java.lang.String date, java.lang.String customerId, java.lang.String server)
          Constructs an Order for a given customer and date with Order data from specified SQL tables.
 
Method Summary
 void appendItem(java.lang.String newItemId, java.lang.String newItemName, java.lang.String newQuantity, java.lang.String unit)
          Appends a new <Item> to the OrderXml.
static void createOrderTable(java.lang.String ordersTableName, java.lang.String server)
          Creates an SQL table suitable for "Orders" data.
 void deleteItem(int itemNumber)
          Deletes a specified <Iitem> from the OrderXml.
static java.lang.String emptyOrder(java.lang.String date, java.lang.String customerId, java.lang.String customerName)
          Returns a string with an empty XML Order for a given customer and date.
 java.lang.String getItemAttribute(int itemNumber, java.lang.String elementName, java.lang.String attributeName)
          Returns a specified item attribute from the OrderXml, or an empty string if the attribute doesn't exist.
 java.lang.String getItemElement(int itemNumber, java.lang.String elementName)
          Returns a specified item element from the OrderXml, or an empty string if the item element doesn't exist.
 java.lang.String getOrderElement(java.lang.String elementName)
          Returns a specified header element from the OrderXml, or an empty string if the element doesn't exist.
 void order2Sql(java.lang.String ordersTableName, java.lang.String server)
          Stores the data from an XML Order into a specified SQL table.
 java.lang.String resolveExternal(java.lang.String publicId, java.lang.String systemId)
          Returns the DTD for "Order" XML documents.
 void setItemAttribute(int itemNumber, java.lang.String elementName, java.lang.String attributeName, java.lang.String newValue)
          Sets a specified attribute of an item element from the OrderXml.
 void setItemElement(int itemNumber, java.lang.String elementName, java.lang.String newValue)
          Sets a specified item element from the OrderXml.
 void setOrderElement(java.lang.String elementName, java.lang.String newValue)
          Sets a specified header element from the Order, and returns the updated OrderXml.
static java.lang.String sql2Order(java.lang.String orderDate, java.lang.String customerId, java.lang.String server)
          Returns an XML "Order" with the data for a given customer_id and order_date.
 
Methods inherited from class jcs.xml.JXml
parse, parse, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

OrderXml

public OrderXml(java.lang.String orderXmlText)
         throws java.lang.Exception
A constructor whose parameter is a String containing a valid XML "Order" document.

This constructor overrides the corresponding constructor of the JXML super class, and performs document validation for the Order DTD.

Parameters:
OrderXmlText - a string that is the Order XML document.
Throws:
java.lang.Exception - Thrown if the argument document is not valid

OrderXml

public OrderXml(java.lang.String date,
                java.lang.String customerId,
                java.lang.String server)
         throws java.lang.Exception
Constructs an Order for a given customer and date with Order data from specified SQL tables.

This method assumes the following SQL tables:

 
  create table customers 
     (customer_id varchar(5) not null unique, 
     customer_name varchar(50) not null)
  create table orders 
     (customer_id varchar(5) not null, 
  order_date datetime not null, 
     item_id varchar(5) not null, 
     quantity int not null)
  create table items 
     (item_id varchar(5) unique, 
     item_name varchar(20),
     unit smallint)
  
Parameters:
orderDate - a string that is the order_date of the requested order. This string must be in an SQL format, such as "1999/05/07".
customerId - a string that is the customer_id of the requested order
server - a string that identifies the SQL server in which to execute the query. See the connectTo method for a description of this parameter.
Throws:
java.lang.ClassNotFoundException - Thrown when the XML parser class cannot be loaded.
java.sql.SQLException - Thrown for any exceptions raised during execution of the SQL statement
java.lang.Exception - Thrown for invalid parameters and other conditions
Method Detail

resolveExternal

public java.lang.String resolveExternal(java.lang.String publicId,
                                        java.lang.String systemId)
                                 throws org.xml.sax.SAXException
Returns the DTD for "Order" XML documents.

Any subclass of the JXml class is expected to have a resolveExternal method such as this. For a description of the role of this method, see the resolveExternal method of JXml.

Parameters:
publicId - the value (if any) specified with the PUBLIC keyword in an external entity reference, or null.
systemId - the value specified with the SYSTEM keyword in an external entity reference.
Returns:
a string with the DTD or other definition of the given external entity.
Throws:
org.xml.sax.SAXException - Thrown when the SYSTEM and PUBLIC names do not define an external entity known by the method. Note that this exception must be a SAXException.
Overrides:
resolveExternal in class JXml

emptyOrder

public static java.lang.String emptyOrder(java.lang.String date,
                                          java.lang.String customerId,
                                          java.lang.String customerName)
                                   throws java.lang.Exception
Returns a string with an empty XML Order for a given customer and date. The OrderXml has no <Item>s.
Parameters:
date - the <Date> for the new OrderXml
customerId - the <CustomerId> for the new OrderXml
customerName - the <CustomerName> for the new OrderXml
Throws:
java.lang.Exception - Thrown when the document can't be created.

getOrderElement

public java.lang.String getOrderElement(java.lang.String elementName)
                                 throws java.lang.Exception
Returns a specified header element from the OrderXml, or an empty string if the element doesn't exist. The elementName is one of "Date", "CustomerId", or "CustomerName".
Parameters:
elementName - the name of one of the above elements of the Order DTD
Returns:
a string with the text of that element or empty.
Throws:
java.lang.Exception - Thrown if the document is not valid.

setOrderElement

public void setOrderElement(java.lang.String elementName,
                            java.lang.String newValue)
                     throws java.lang.Exception
Sets a specified header element from the Order, and returns the updated OrderXml. The elementName is one of "Date", "CustomerId", or "CustomerName".
Parameters:
elementName - the name of one of the above elements of the Order DTD
newValue - the new text of the element
Returns:
an OrderXml object with the updated document
Throws:
java.lang.Exception - Thrown if the elementName is not valid

getItemElement

public java.lang.String getItemElement(int itemNumber,
                                       java.lang.String elementName)
                                throws java.lang.Exception
Returns a specified item element from the OrderXml, or an empty string if the item element doesn't exist. The itemNumber is the number of an item in the document (starting with 0). The elementName is one of "ItemId", "ItemName",or "Quantity".
Parameters:
itemNumber - the number of an Item in the OrderXml
elementName - the name of one of the above elements of the Order DTD
Returns:
a string with the text of that element, or null if it doesn't exist.
Throws:
java.lang.Exception - if the document is not valid.

setItemElement

public void setItemElement(int itemNumber,
                           java.lang.String elementName,
                           java.lang.String newValue)
                    throws java.lang.Exception
Sets a specified item element from the OrderXml. The itemNumber is the number of an item in the document (starting with 0). The elementName is one of "ItemId", "ItemName",or "Quantity". The newValue is the replacement value for the element.
Parameters:
itemNumber - the number of an Item in the OrderXml
elementName - the name of one of the above elements of the Order DTD
newValue - the new value for the specified element
Returns:
an OrderXml with the updated document
Throws:
java.lang.Exception - Thrown if the item element doesn't exist.

getItemAttribute

public java.lang.String getItemAttribute(int itemNumber,
                                         java.lang.String elementName,
                                         java.lang.String attributeName)
                                  throws java.lang.Exception
Returns a specified item attribute from the OrderXml, or an empty string if the attribute doesn't exist. The itemNumber is the number of an item in the document (starting with 0). The elementName is one of "ItemId", "ItemName",or "Quantity". The attributeName is the name of an attribute of the element named elementName. In the Order DTD, only one element has an attribute, namely the unit attribute of the quantity element. This method is written for the general case, for illustration.
Parameters:
itemNumber - the number of an Item in the OrderXml
elementName - the name of one of the above elements of the Order DTD
Returns:
a string with the text of that element
Throws:
java.lang.Exception - Thrown if the elementName is not valid

setItemAttribute

public void setItemAttribute(int itemNumber,
                             java.lang.String elementName,
                             java.lang.String attributeName,
                             java.lang.String newValue)
                      throws java.lang.Exception
Sets a specified attribute of an item element from the OrderXml. The itemNumber is the number of an item in the document (starting with 0). The elementName is one of "ItemId", "ItemName",or "Quantity". The attributeName is the name of an attribute of the element elementName. The newValue is the replacement value for the attribute. In the Order DTD, only one element has an attribute, namely the unit attribute of the quantity element. This method is written for the general case, for illustration.
Parameters:
itemNumber - the number of an Item in the OrderXml
elementName - the name of one of the above elements of the Order DTD
newValue - the new value for the specified element
Returns:
an OrderXml with the updated document
Throws:
java.lang.Exception - Thrown if the elementName is not valid

appendItem

public void appendItem(java.lang.String newItemId,
                       java.lang.String newItemName,
                       java.lang.String newQuantity,
                       java.lang.String unit)
                throws java.lang.Exception
Appends a new <Item> to the OrderXml.
Parameters:
newItemId - the <ItemId> for the new <Item>
newItemName - the <ItemName> for the new <Item>
newQuantity - the <Quantity> for the new <Item>
unit - the "unit" attribute for the <Quantity>
Throws:
java.lang.Exception - Thrown if the elementName is not valid

deleteItem

public void deleteItem(int itemNumber)
                throws java.lang.Exception
Deletes a specified <Iitem> from the OrderXml.

The itemNumber is the number of an item in the document (starting with 0).

Parameters:
itemNumber - the number of an Item in the OrderXml
Throws:
java.lang.Exception - Thrown if the elementName is not valid

sql2Order

public static java.lang.String sql2Order(java.lang.String orderDate,
                                         java.lang.String customerId,
                                         java.lang.String server)
                                  throws java.lang.ClassNotFoundException,
                                         java.sql.SQLException,
                                         java.lang.Exception
Returns an XML "Order" with the data for a given customer_id and order_date.

This method assumes the following SQL tables:

 
  create table customers 
     (customer_id varchar(5) not null unique, 
     customer_name varchar(50) not null)
  create table orders 
     (customer_id varchar(5) not null, 
      order_date datetime not null, 
      item_id varchar(5) not null, 
      quantity int not null)
  create table items 
     (item_id varchar(5) unique, 
     item_name varchar(20),
     unit smallint)
  
Parameters:
orderDate - a string that is the order_date of the requested order. This string must be in an SQL format, such as "1999/05/07".
customerId - a string that is the customer_id of the requested order
server - a string that identifies the SQL server in which to execute the query. See the connectTo method for a description of this parameter.
Returns:
a string with the output XML document that contains the XML "Order" representation of the order
Throws:
java.lang.ClassNotFoundException - Thrown when the XML parser class cannot be loaded.
java.sql.SQLException - Thrown for any exceptions raised during execution of the SQL statement
java.lang.Exception - Thrown for invalid parameters and other conditions

order2Sql

public void order2Sql(java.lang.String ordersTableName,
                      java.lang.String server)
               throws java.lang.Exception
Stores the data from an XML Order into a specified SQL table.

The name of the table is a parameter, but the column names and datatypes are assumed to be as follows (using the parameter names for the table names):

 
  create table ordersTableName
    (customer_id varchar(5) not null, 
    order_date datetime not null, 
    item_id varchar(5) not null, 
    quantity int not null,
    unit smallint)
  

The insert statements that this method performs specify the inserted column names, so the actual tables can have other columns not shown above (such columns must allow nulls).

For a description of the server parameter, see the connectTo method.

Parameters:
ordersTableName - a string that is the name of the 'Orders' table
server - a string that identifies the server in which to execute the statement
Throws:
java.lang.Exception - Thrown for parse errors.

createOrderTable

public static void createOrderTable(java.lang.String ordersTableName,
                                    java.lang.String server)
                             throws java.lang.Exception
Creates an SQL table suitable for "Orders" data. The table name is a parameter. The column names and datatypes are fixed:
 
  create table ordersTableName
    (customer_id varchar(5) not null, 
    order_date datetime not null, 
    item_id varchar(5) not null, 
    quantity int not null,
    unit smallint)
  

This method is a convenience for creating the sort of table needed for the storeOrder method.

For a description of the server parameter, see the connectTo method.

Parameters:
ordersTableName - a string that will be the name of the 'Orders' table
server - a string that identifies the server in which to execute the statement.
Throws:
java.lang.Exception - Thrown for SQL errors.