Index
- Specification
- Structure of XML Class
- DOM and SAX
- DTD and XMLSchema
- Create XML Document
- Develop Web Service
- Restrictions
Specification
The XML-related classes included in SophiaFramework UNIVERSE, whose names start with "SFXXML ... ", are classified into the following three categories.
- Create an XML document
- Parse an XML document
- Process Web Services by using the WSDL or SOAP APIs
[ Major Features ]
- DTD and XMLSchema are available.
- The DOM parser and the SAX parser are available.
- WSDL 1.1 and SOAP 1.1 and 1.2 are supported.
- Secure Web services over HTTPS are supported.
* SOAP Attachment is NOT implemented. And as for SOAP Fault, only SOAP 1.1 is supported.
SOAP ( Simple Object Access Protocol )
WSDL ( Web Services Description Language )
Structure of XML Class
Classes for Creating Nodes of the DOM Tree
SophiaFramework UNIVERSE provides you with the following 12 types of node classes for the DOM tree defined by W3C ( World Wide Web Consortium ). These classes inherit from the class named "SFXXMLNode".
[ SFXXMLNode Inheritance Relation ]
| Class name | Description | NodeType |
|---|---|---|
| SFXXMLNode | Abstract node | - |
| SFXXMLElement | Element node | ELEMENT_NODE |
| SFXXMLAttribute | Attribute node | ATTRIBUTE_NODE |
| SFXXMLText | Text node | TEXT_NODE |
| SFXXMLCDATASection | CDATASection node | CDATA_SECTION_NODE |
| SFXXMLEntityReference | EntityReference node | ENTITY_REFERENCE_NODE |
| SFXXMLEntity | Entity node | ENTITY_NODE |
| SFXXMLProcessingInstruction | Processing Instruction node | PROCESSING_INSTRUCTION_NODE |
| SFXXMLComment | Comment node | COMMENT_NODE |
| SFXXMLDocument | Document node | DOCUMENT_NODE |
| SFXXMLDocumentType | DocumentType node | DOCUMENT_TYPE_NODE |
| SFXXMLDocumentFragment | DocumentFragment node | DOCUMENT_FRAGMENT_NODE |
| SFXXMLNotation | Notation node | NOTATION_NODE |
Basic Function of SFXXMLNode
Function to Get a Node from the DOM Tree
| Function Name | Description |
|---|---|
| GetFirstChild | get the first child node |
| GetLastChild | get the last child node |
| GetNextSibling | get the next sibling node amongst |
| GetPreviousSibling | get the previous sibling node |
| GetParentNode | get the parent node |
Function to Create or Update a Node of the DOM Tree
| Function Name | Description |
|---|---|
| AppendChild | append a child node |
| RemoveChild | remove a child node |
| ReplaceChild | replace a child node |
| InsertBefore | insert a node |
| CloneNode | clone a node |
Function to Get or Set a Node Attribute of the DOM Tree
| Function Name | Description |
|---|---|
| HasChildNodes | test if it has a child node |
| GetChildNodes | get all the child nodes |
| GetNodeType | get a node type |
| GetNodeName | get a node name |
| GetNodeValue | get node contents |
| SetNodeValue | set node contents |
| GetText | get texts included in all the child nodes |
| SetText | set a text into its child node |
Function to Compare Nodes
| Function Name | Description |
|---|---|
| IsSameNode | test if two nodes are same |
| EqualNode | test if two nodes are equal |
Structure of the DOM Tree
[ Process Flow on XML parser ]
An XML parser receives XML documents grammatically checked by DTD or XMLSchema, expands the documents onto memory as tree-structured objects, and sends them to an application.
In SophiaFramework UNIVERSE, the XML parser ( SFXDOMParser / SFXXSDDOMParser ) is created and analyzes an XML document, and gets the DOM tree of SFXXMLDocument.
[ Sequence Diagram ]
-
Basic Function of "SFXXMLDocument"
The most important object in parsing an XML document is the root node of SFXXMLDocument in the DOM tree.
1. get, create, update, and compare a node of the DOM tree
2. create a new node type
3. save XML document
4. get any node of the DOM tree as Helper function
DOM and SAX
There are two kinds of XML parsers. One is the DOM parser, and the other is the SAX parser.
The DOM parser expands XML document onto memory as a DOM tree. With the DOM parser, it is very easy to operate an XML document, but usually a lot of memory is necessary.
The SAX parser is a set of APIs that reads XML document sequentially from the beginning and processes it in an event driven style. It needs less memory and is faster than DOM, but there is no update function for XML documents such as adding, deleteing a node etc.
SophiaFramework UNIVERSE provides you with SFXXMLDOMParser / SFXXSDDOMParser as the DOM parser, SFXXMLSAXParser as the SAX parser.
Basic Function of SFXXMLDOMParser and SFXXMLSAXParser
Parse
| Function Name | Description |
|---|---|
| Parse | read and parse XML document |
Set / Get a parser attribute
By default, the attribute value is set to " false " except the SetIgnoreAnnotations function.
| Function Name | Description |
|---|---|
| SetGrammar | set grammar used by parser |
| Set / GetDoNamespaces | set / get the value if Namespace should be processed |
| Set / GetDoIndent | set / get the value if statements should be indented |
| Set / GetDoSchema | set / get the value if schema should be processed |
| Set / GetCreateCommentNodes | set / get the value if comment node should be created |
| Set / GetValidationSchema | set / get the value if XML document should be validated by XMLSchema |
| Set / GetValidationDTD | set / get the value if XML document should be validated by DTD |
| Set / GetLoadExternalDTD | set / get the value if external DTD file of XML document with DTD should be loaded |
| Set / GetIgnoreAnnotations | set / get the value if annotation elements file of XML document with XMLSchema should be ignored |
| SetSchemaLocation | set XSD file of XML document with XMLSchema |
| GetDocument | get the root node of the DOM tree |
Helper function
Only available for the SFXXMLDOMParser class, not available for the SFXXMLSAXParser class.
| Function Name | Description |
|---|---|
| GetFirstChildElement | get the first child node of the node passed as argument |
| GetFirstChildElementNS | get the first child node of the node with namespace passed as argument |
| GetNextSiblingElement | get the next sibling node of the node passed as argument |
| GetNextSiblingElementNS | get the next sibling node of the node passed as argument with namespace |
* To parse by using the SFXXMLSAXParser class, it is necessary to create a class inheriting the SFXXMLDefaultHandler class for setting a handler interface to notify events.
DTD and XMLSchema
DTD and XMLSchema are grammars to validete whether XML document is configured in an adequate format when XML parser analyzes it.
In DTD, data type cannot be defined, and its grammar is not described in XML.
The statements of XMLSchema are described in XML format. Definition of data type and namespace not included in DTD are available in XMLSchema.
SophiaFramework UNIVERSE supports DTD and XMLSchema. When DTD or XMLSchema are used, an error will occur if some data of XML document violate it.
Process XML Document with DTD
In processing an XML Document with DTD, Set / GetValidationDTD or Set / GetLoadExternalDTD of SFXXMLDOMParser / SFXXMLSAXParser are used. When its DTD is defined as another file ( external DTD file ) different from the XML document, the external DTD file should be loaded in settings SetLoadExternalDTD "true".
The following operations are available after getting the SFXXMLDocumentType object from the DOM tree.
| Function Name | Description |
|---|---|
| GetEntities | get all the entities defined in DTD |
| GetNotations | get all the notations defined in DTD |
| GetPublicID | get public ID of external subset |
| GetSystemID | get system ID of external subset |
Process XML Document with XMLSchema
In processing XML Document with XMLSchema, Set / GetDoSchema, Set / GetValidationSchema, Set / GetIgnoreAnnotations or SetSchemaLocation of SFXXMLDOMParser / SFXXMLSAXParser are used.
If SetDoNamespaces is "true", namespace can be set.
Create XML Document
By using the SFXXMLDocument class, a DOM tree is expanded onto memory and saved as a file by using the save function.
Outline
The SFXXMLDocument object is the root node of the DOM tree.
You should create a node by using the CreateXXXXXXXXX function, and then create and update a DOM tree of SFXXMLNode.
All the nodes should be managed by the root node of SFXXMLDocument.
[ Fundamental Process Flow ]
SFXXMLElementPtr element = document.CreateElement("new_node");
// create new node
document.AppendChild(element); // save at specified position
Create XML Document with Namespace
The SFXXMLDocument::CreateElementNS and SFXXMLDocument::CreateAttributeNS functions are provided for processing namespace in the SFXXMLDocument class.
In XML document with namespace, the name format of element or attribute is divided into Prefix ( "prefix" ) and Local Name ( "localname" ) like [ prefix:localname ], which is called "Qualified Name".
When creating an element by using the SFXXMLDocument::CreateElementNS function, an attribute of [ xmlns:'prefix'="URI" ] is automatically created.
When using the SFXXMLDocument::CreateAttributeNS funtion, namespace must be set by using the SFXXMLElement::SetAttribute funtion.
Develop Web Service
There are three fundamental technologies of SOAP, WSDL and UDDI in the Web service. All the data is described in XML format, and those services are implemented by using internet protocol such as HTTP / SMTP etc.
In SophiaFramework UNIVERSE, the SOAP classes of SFXSOAPParser / SFXSOAPWriter / SFXSOAPRPC are provided. In the SFXSOAPParser / SFXSOAPWriter / SFXSOAPRPC classes, function to operate SOAP message and communicate by RPC ( Remote Procedure Call ) are provided.
SOAP : Simple Object Access Protocol
SOAP message consists of three elements: Envelope, Header and Body. SFXSOAPParser class inherites SFXXMLDOMParser class and expands the DOM tree onto memory. You have only to analyze SOAP message to get any information on SOAP message. Getting the DOM tree is not needed.
Main Funtion of SFXSOAPParser
| Function Name | Description |
|---|---|
| GetEnvelope | get Envelope element of SOAP message |
| GetHeader | get Header element of SOAP message |
| GetBody | get Body element of SOAP message |
| GetFault | get Fault element of SOAP message |
Main Function of Helper Function
| Function Name | Description |
|---|---|
| GetBodyEntries | get all the entry nodes in the body of SOAP message |
| GetHeaderEntries | get all the entry nodes in the header of SOAP message |
| GetBodyEntry | get an entry node in the body of SOAP message |
| GetHeaderEntry | get an entry node in the header of SOAP message |
| GetRPCParameter | get parameter element in the body of SOAP message |
| GetRPCResult | get the first child element of the first entry in the body of SOAP message |
| GetRPCStruct | get the first entry in the body of SOAP message |
SFXSOAPWriter is a class to create each element of SOAP document by using the SFXXMLDocument class.
SFXSOAPRPC is a class to implemet SOAP-RPC protocol by using the SFXSOAPParser and SFXSOAPWriter classes.
To call Web service, you have only to set the function name of Web service, targetted URI, parameters, IP address of Web service, Web service and its soapAction attribute, and the callback function.
Set the SOAP message created by using the SFXSOAPWriter class to the parameter of SFXSOAPRPC::Invoke function, and call the Web service. In the shortest case, its code size may be less than 10 lines.
Input Parameter
When using SFXSOAPRPC, you have to correctly set parameters based on SOAP documents.
In case of SFXSOAPServiceProxy, you have only to set the input parameters described in WSDL document.
Analyze replied SOAP message
When using SFXSOAPRPC and SFXSOAPServiceProxy, you connect a server through the HTTP / HTTPS protocol.
And you get replied message in SOAP format by using the callback function. The replied SOAP mesage should be analyzed by one of the following three methods. Usually, the third method of using SFXSOAPParser is chosen.
-
Each element is selected by the helper function of the SFXSOAPRPC class such as a GetResultValueByName function.
-
SOAP message is analyzed by using the SFXSOAPParser class.
When maxOccurs="unbounded" is defined in the WSDL document, there is a possibility that same name parameters may exist in the elements defined by XMLSchema. In this case, the last parameter is saved and the other parameters are ignored in Sophiaframework.
When SOAP message including SOAP Fault is replied from a server, the error value to be notified to the callback function will be SFERR_SOAP_FAULT_MESSAGE. Detailed error information is obtained by using the SFXSOAPRPC::FAULT structure.
Restrictions
- As for encoding, Shift_JIS, UTF-8, and EUC-JP are supported.
- XML parsers need a lot of memory. In particular, much heap memory is necessary when DTD, XMLSchema, or WSDL is used.
- XML specification of W3C ( World Wide Web Consortium ) may be updated in the future.