ws-axis-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r389181 - in /webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp: ./ arch/ images/c/
Date Mon, 27 Mar 2006 16:03:42 GMT
Author: dicka
Date: Mon Mar 27 08:03:40 2006
New Revision: 389181

Updates to Axis C++ Website documentation.

- addition of Trace guide
- addition of XSD Objects developers guide (previously only available within package, not
on web site)
- updates to Contributors list

  (with props)
  (with props)
  (with props)
  (with props)
  (with props)

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/TraceGuide.ihtml
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/TraceGuide.ihtml
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/TraceGuide.ihtml
Mon Mar 27 08:03:40 2006
@@ -0,0 +1,111 @@
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>The Axis C++ Trace Guide</title>
+<meta name="generator"
+	content="amaya 8.1b, see">
+<P>This documents describes the trace facilities within Axis C++, how to
+enable them and how to make use of the produced trace.</P>
+	<LI><A href="#RuntimeTrace">Runtime Trace</A>
+	<UL>
+		<LI><A href="#enablingRuntimeTrace">Enabling runtime trace</A></LI>
+		<LI><A href="#readingRuntimeTrace">Reading runtime trace</A></LI>
+	</UL></LI>
+	<LI><A href="#StartupTrace">Startup Trace</A>
+	<UL>
+		<LI><A href="#enablingStartupTrace">Enabling startup trace</A></LI>
+	</UL></LI>
+	<LI><A href="#InterestingTraceEntries">Interesting Trace Entries</A></LI>
+<P><a name="RuntimeTrace"></a></P>
+<H1>Runtime Trace</H1>
+<P>To aid the development team in understanding the problems of users,
+the Axis C++ engine has been instrumented with trace.</P>
+<P><A name="enablingRuntimeTrace"></A></P>
+<H2>Enabling runtime trace</H2>
+<P>Trace is enabled at runtime by adding the following to <CODE>axiscpp.conf</CODE>:</P>
+<P><CODE>ClientLogPath:&lt;path to log file&gt;</CODE></P>
+<P><A name="readingRuntimeTrace"></A></P>
+<H2>Reading runtime trace</H2>
+<P>The Axis C++ runtime trace is produced in a format compatible with
+the Trace Analyzer for WebSphere Application Server, which is available
+from here:</P>
+<P><A href="">Trace Analyzer
+for WebSphere Application Server</A></P>
+<P>However, it is also possible to use any text editor.  Each line is made up of the
following columns:</P>
+	<LI>thread ID</LI>
+	<LI>Class name, a - indicates a c-style gloval function</LI>
+	<LI>Trace type:
+	<UL>
+		<LI>&gt; (entry)</LI>
+		<LI>&lt; (exit)</LI>
+		<LI>X (exception)</LI>
+		<LI>I (information)</LI>
+	</UL></LI>
+	<LI>Method name</LI>
+	<LI><CODE>this</CODE> pointer for instance methods</LI>
+	<LI>comma seperated list of parameters
+	<UL>
+		<LI>[nnnnnnnn] Data in hex</LI>
+		<LI>&lt;...&gt; Data in ascii</LI>
+		<LI>For pointers address is given before data</LI>
+		<LI>For void*, only 1st byte of data is given, as there is no way of knowing size
of data.</LI>
+	</UL></LI>
+<P>So, a typical entry would be:</P>
+<P><CODE>[27/03/2006 16:21:48:945 Time] 4220 AxisConfig &gt; getAxisConfProperty
@00376358,[00000000] &lt;....&gt;</CODE></P>
+<P>Some other things to watch for are:</P>
+	<LI>An entry containing: <CODE>------------&gt;</CODE> indicates that
it is a multiline entry</LI>
+	<LI><CODE>&lt;BADPOINTER&gt;</CODE> means the trace attempted
to dereference a pointer causing a SIGSEGV which the trace has caught.</LI>
+	<LI><CODE>&lt;UNKNOWNTYPE&gt;</CODE> means the trace tool and
runtime have got out of step.  You have found a bug!</LI>
+	<LI><CODE>&lt;ANONYMOUS&gt;</CODE> means that it is unnamed in
the method signature.</LI>
+<P><a name="StartUpTrace"></a></P>
+<H1>Startup Trace</H1>
+<P>One shortcoming of the runtime trace is that it only begins tracing
+after the configuration file has been loaded and the <CODE>ClientLogPath</CODE>
+entry read. This means any problems that occur before this, for example
+while reading the configuration file, are missed. To overcome this the
+Axis C++ engine has also been instrumented with startup trace, this
+starts tracing at the first call into the Axis engine and everything up
+to the point at which runtime trace starts.</P>
+<P>Startup trace uses the same formatting as the runtime trace.</P>
+<P><A name="enablingStartupTrace"></A></P>
+<H2>Enabling startup trace</H2>
+<P>Startup trace is enabled by setting the following environment
+<P><CODE>AXISCPP_STARTUP_TRACE=&lt;path to startup log file&gt;</CODE></P>
+<P><a name="InterestingTraceEntries"></a></P>
+<H1>Interesting Trace Entries</H1>
+<P>Here are a few entries well worth looking for when you first receive
+a trace file.</P>
+<H2>Stub Destructor</H2>
+<P>Check lines in the trace file immediately preceding the entry for
+~Stub, as this is typically the first method run following a <CODE>SIGSEGV</CODE>.</P>
+<H2>Exception Entries</H2>
+<P>Check any exception entries, which is indicated by an X in the 3rd
+column. These actually indicate that an exception has been caught. If
+you see <CODE>@&lt;number&gt;</CODE> this indicates which catch block,
+if more than one present in the current method. You can use this, along
+with the trace lines immediately preceding, to determine fairly closely
+exactly where the trace was thrown. You will also see trace entries for
+the exception constructor if it is an Axis C++ exception.</P>
+<P>The entry trace for <CODE>operator&lt;&lt;</CODE> on <CODE>HTTPChannel</CODE>shows
+the message that will sent on the wire. Although the HTTP Header and
+SOAP message tend to be in seperate calls to this method. This allows
+for diagnosis of some problems with the message, without requiring the
+use of a tcp/ip monitoring tool.</P>

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/XSD_Objects.ihtml
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/XSD_Objects.ihtml
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/XSD_Objects.ihtml
Mon Mar 27 08:03:40 2006
@@ -0,0 +1,133 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<META name="GENERATOR" content="IBM Software Development Platform">
+<H1 align="center">XSD Objects</H1>
+<H2>XML Schema Part 2 : Datatypes</H2>
+<P>The types and formatting of data transmitted in a SOAP message is defined by the
XML Schema, in particular Part 2 : Datatypes. The full specification can be seen <A
+	href="">here</A>.</P>
+<H3>Built-in types</H3>
+<P>Within <A
+	href="">section
+3</A>  of the above specification 44 built-in datatypes are described, encompasing
Strings, numeric, time and encoded binary datatypes. These datatypes are split into two groups,
primitive and derived types.</P>
+<P><IMG border="1" src="../images/c/XSD_Objects_Heirarchy.JPG" width="680"
+	height="588"></P>
+<H4>Primitive Types</H4>
+<P>The XML schema provides 19 primitive types. As all data is represented in text form
within XML, the value space for each datatype needs to be specified, for example numeric types
cannot  contain alphabetic characters. To do this, each type defines a number of contraining
facets and the values within these facets allows the XML engine to validate the data. See
+	href="#Constraining Facets">Constraining Facets</A> below for further information
on how these are used.</P>
+<P><IMG border="1" src="../images/c/XSD_PrimitiveTypes.JPG" width="680"
+	height="233" alt="The 19 primitive data types are: string, boolean, decimal, float, double,
duration, dateTime, time, date, gYearMonth, gYear, gMonthDay, gDay, gMonth, hexBinary, base64Binary,
anyURI, QName, NOTATION"></P><P>See <A
+	href="">section
+3.2</A> of the specification for full detail on each datatype.</P>
+<H4>Derived Types</H4>
+<P>The XML Schema allows additional types to be derived from the primitive types, and
has 25 built-in derived types. 12 data types are derived from the string primitive data type.</P>
+<IMG border="1" src="../images/c/XSD_String_DerivedTypes.JPG" width="252"
+	height="359" alt="The 12 types derived from the string primitive data type are: normalizedString,
+<P>The remaining 13 data types are derived from the decimal primitive data type.</P>
+<P><IMG border="1" src="../images/c/XSD_Decimal_DerivedTypes.JPG"
+	width="503" height="359" alt="The 13 data types derived from the decimal primitive data
type are: integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger,
unsignedLong, unsignedInt, unsignedShort, unsignedByte, positiveInteger"></P>
+<P>A derived type uses the same contraining facets as the type from which it is derived,
but provides differing values for one or more facet so as to further restrict the value space.
For example; the decimal allows fraction digits, while the integer derived type sets this
facet to 0.</P><P>See <A
+	href="">section
+3.3</A> of the specification for full detail on each datatype.</P>
+<H4>User defined derived types</H4>
+<P>In the same way as the XML Schema defines a number of built-in datatypes the user
can also provide additional derived types. This can be done in the WSDL document, or an XSD
referred from a WSDL document.</P>
+<P>The following shows how you can create a new type called <code>direction</code>,
which is derived from the <code>NMTOKEN</code> built-in type, to only have the
values <code>fromKey</code> and <code>toKey</code>, by restricting
the <code>enumeration</code> constraining facet.</P>
+<PRE>	&lt;xsd:simpleType name="direction"&gt;
+		&lt;xsd:restriction base="NMTOKEN"&gt;
+			&lt;xsd:enumeration value="fromKey"/&gt;
+			&lt;xsd:enumeration value="toKey"/&gt;
+		&lt;/xsd:restriction&gt;
+	&lt;/xsd:simpleType&gt;</PRE>
+<H3><A name="Constraining Facets">Constraining Facets</A></H3>
+<P>As mentioned above, the value spaces of each of the built-in types are controlled
by constraining facets. The XML Schema provides 12 constraining facets, as described in <A
+	href="">section
+<P>The 12 constraining facets are:</P>
+<LI><code>pattern</code> - describes the form of the data, typically using
regular expression syntax.</LI>
+<LI><code>enumeration</code> - specifies a fixed set of permitted values</LI>
+<LI><code>whiteSpace</code> - how to handle whitespace characters</LI>
+<LI><code>preserve</code> - value is unchanged</LI>
+<LI><code>replace</code> - all occurances of tab, line feed and carriage
return are replaced with a space</LI>
+<LI><code>collapse</code> - after the process of <CODE>replace</CODE>,
remove all contigious repeating occurances of spaces, and strip leading and trailing spaces</LI>
+<P>Each primitive datatype uses a subset of these contraining facets, to suit the characteristics
of that particular datatype. <A
+	href="">Section
+4.1.5</A> of the XML Schema provides a table of which facets are used for each datatype.</P>
+<P>It is permitted for the value of a constraining facet to be undefined, with the
exception of whitespace which must be specified as one of preserve, replace or collapse.</P>
+<H1 align="center">Axis C++ Implementation of XSD built-in types</H1>
+<H2>C++ Objects</H2>
+<P>In version 1.5 of Apache Axis C++, an object model was introduced to the SOAP engine
for the XSD built-in types. The object heirarchy mimics the order in which the datatypes are
derived from each other.</P>
+<H3>IAnySimpleType Interface</H3>
+<P>All the XSD type objects implement the IAnySimpleType interface, which provides
the following methods, which must be implemented by all implementing classes</P>
+<code>AxisChar* serialize() throw (AxisSoapException)</code><BR>
+<code>void deserialize(const AxisChar* valueAsChar) throw (AxisSoapException)</code><BR>
+<code>XSDTYPE getType()</code><BR>
+<code>void* getValue()</code>
+<P>In addition each implementation of this interface must provide a parameterized constructor,
such that it can be constructed and will immediately serialize the provided value.</P>
+<P>The IAnySimpleType interface provides the following utility method, which should
be called by all implementing classes when serializing data.</P>
+<code>AxisChar* serialize(const AxisChar* value) throw (AxisSoapException);</code>
+<P>This method resolves reserved characters (eg <code>&amp;</code>
is replaced by <code>&amp;amp;</code>), processes <code>Whitespace</code>,
validates <code>Pattern</code> and ensures value is contained within <code>Enumeration</code>.</P>
+<H3>Object Heirarchy</H3>
+<P>Below is a portion of the C++ object heirarchy, which, as you will notice, is very
similar to the <A
+	href="">diagram
+of built-in datatypes</A> in the XSD Schema.</P>
+<P><IMG border="1" src="../images/c/XSDObjects_Heirarchy.gif" width="824"
+	height="717"></P>
+<H3>Mapping XSD built-in types to C/C++ types</H3>
+<P>Within the Axis engine mappings are provided between the XSD built-in types and
the native C/C++ types. To aid understanding and maintain consistency, these are declared
as typedefs to match the XSD type names. These typedefs should be used throughout the engine
+<LI>Clarity of code, making it clear which type is being handled at any point in the
+<LI>Ease of maintenance, should a native type need to be altered, it need only be done
in the typedef without further changes through the codebase.</LI>
+<H4>C++ Types</H4>
+<P>The mapping from C++ types to the XSD built-in types is defined in <code>AxisUserAPI.hpp</code>.
For each XSD built-in type a corresponding typedef is declared in the form <code>xsd__&lt;<I>type</I>&gt;</code>,
eg: <code>xsd__string</code>.</P>
+<P>Note: <code>AxisUserAPI.hpp</code> only declares those types currenty
supported within the user API.</P>
+<H4>C Types</H4>
+<P>Similar to the C++ API, the mapping from C types to the XSD built-in types is defined
in <code>AxisUserAPI.h</code>. A typedef is declared for each XSD built-in type,
in the form <code>xsdc__&lt;<I>type</I>&gt;</code>, eg: <code>xsdc__string</code>.</P>
+<H3>IConstrainingFacet Interface</H3>
+<P>All the Constraining Facet objects implement the IConstrainingFacet interface. This
provides the following utility method, which allows the XSD objects to determine if a given
facet has been defined:</P>
+<UL><code>bool isSet();</code></UL>
+<P>The following Constraining Facet objects provide utility methods to assist the serialization/deserialization
of XSD built-in types:</P>
+<UL><code>void validateEnumeration(const AxisChar* value) throw (AxisSoapException);</code></UL>
+<UL><code>void validatePattern(const AxisChar* value) throw (AxisSoapException);</code></UL>
+<UL><code>const AxisChar* processWhiteSpace(const AxisChar* valueToProcess);</code></UL>
+<H1>Current Limitations</H1>
+<H2>Function Limitation</H2>
+<P>Currently, the XSD objects are completely internal to the Axis engine. In the future
we may wish to expose these on the external API, such that customers (via WSDL2Ws) will be
able to derive additional simple types simply by refining one or more of the constraining
facets, then simply re-using the serialization/deserialization logic we have already written.</P>
+<H2>Pattern Constraining Facet</H2>
+<P>The implementation of the pattern constraining facet is incomplete. It needs to
validate against a given regular expression, following this, the pattern for each of data
types needs to be updated with the regular expression to describe their particular data type.</P>
+<P>XML Schema Part 2 : Datatypes - <A href=""></A></P>
+<H2>Outstanding Issues</H2>
+<A href="">AXISCPP-291</A> -
dateTime unable to support dates prior to 1970.

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/documentation.ihtml
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/documentation.ihtml
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/documentation.ihtml
Mon Mar 27 08:03:40 2006
@@ -34,15 +34,12 @@
 <li><a href="antbuild-guide.html">ANT Build Guide</a></li></ul>
 <H1>Reference Material</H1>
-<a href="arch/ArchitectureGuide.html"><A href="arch/WSDL2Ws.html">WSDL2Ws
-	Tool</A>
-	<LI><A href="arch/ArchitectureGuide.html"><A
-		href="arch/mem-management.html">Memory Management Guide</A>
-	<LI><A href="arch/ArchitectureGuide.html">Architecture Guide</A></LI>

+<LI><A href="TraceGuide.html">Trace Guide</A></LI> 
+<li><A href="arch/WSDL2Ws.html">WSDL2Ws Tool</A></li>
+<LI><A href="arch/mem-management.html">Memory Management Guide</A></LI>
+<LI><A href="arch/XSD_Objects.html">XSD Objects Implementation Reference</A>
+<LI><A href="arch/ArchitectureGuide.html">Architecture Guide</A></LI>


Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSDObjects_Heirarchy.gif
Binary file - no diff available.

Propchange: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSDObjects_Heirarchy.gif
    svn:mime-type = application/octet-stream

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_Decimal_DerivedTypes.JPG
Binary file - no diff available.

Propchange: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_Decimal_DerivedTypes.JPG
    svn:mime-type = application/octet-stream

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_Objects_Heirarchy.JPG
Binary file - no diff available.

Propchange: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_Objects_Heirarchy.JPG
    svn:mime-type = application/octet-stream

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_PrimitiveTypes.JPG
Binary file - no diff available.

Propchange: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_PrimitiveTypes.JPG
    svn:mime-type = application/octet-stream

Added: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_String_DerivedTypes.JPG
Binary file - no diff available.

Propchange: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/images/c/XSD_String_DerivedTypes.JPG
    svn:mime-type = application/octet-stream

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/who.ihtml
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/who.ihtml (original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/who.ihtml Mon
Mar 27 08:03:40 2006
@@ -8,79 +8,39 @@
 <h1>The Axis C++ team</h1>
 <h2>Active Contributors</h2>
-<p>Susantha Kumara &lt;,;,</p>
-<p>Damitha Kumarage &lt;,;,</p>
-<p>Roshan Weerasuriya &lt;,;,</p>
-<p>Sanjaya Singharage
 <p>John Hawkins &lt;;, </p>
-<p>Samisa Abeysinghe &lt;;, </p>
 <p>Fred Preston &lt;;, </p>
-<p>Mark Whitlock &lt;;, </p>
-<p>Andrew Perry &lt;;, </p>
-<p>Adrian Dick &lt;;, </p>
-<p>Sanjiva Weerawarana &lt;;, </p>
-<p>Farhaan Mohideen &lt;;, </p>
-<p>Nithyakala Thangarajah &lt;;, </p>
-<p>Rangika Mendis &lt;;, </p>
-<p>Sharanka Perera &lt;;, </p>
-<p>M.F.Rinzad Ahamed &lt;;, </p>
+<p>Adrian Dick &lt;;</p>
+<P>Nadir Amra &lt;;</P>
 <h2>Additional Contributors</h2>
-<p>Chaminda Divitotawela &lt;,;,</p>
+<p>Samisa Abeysinghe &lt;;, </p>
+<P>Mark Whitlock &lt;;,</P>
+<P>Andrew Perry &lt;;,</P>
+<P>Sanjiva Weerawarana &lt;;,</P>
+<P>Farhaan Mohideen &lt;;,</P>
+<P>Nithyakala Thangarajah &lt;;,</P>
+<P>Rangika Mendis &lt;;,</P>
+<P>Sharanka Perera &lt;;,</P>
+<P>M.F.Rinzad Ahamed &lt;;,</P>
+<P>Susantha Kumara &lt;,;,</P>
+<P>Damitha Kumarage &lt;,;,</P>
+<P>Roshan Weerasuriya &lt;,;,</P>
+<P>Sanjaya Singharage &lt;,;,</P>
+<p>Chaminda Divitotawela &lt;,;,</p>
 <p>Nuwan Gurusinghe &lt;,;,</p>
 <p>Chamindra de Silva &lt;;,</p>
 <p>Kanchana Welagedara &lt;;,</p>
 <p>Srinath Perera &lt;,;,</p>
-<p>Thushantha Ravipriya De Alwis &lt;,;,</p>
-<p>Dimuthu Leelarathne &lt;,;,</p>
+<p>Thushantha Ravipriya De Alwis &lt;,;,</p>
+<p>Dimuthu Leelarathne &lt;,;,</p>
 <p>Jeyakumaran.C &lt;;,</p>
 <p>Vairamuthu Thayapavan &lt;;,</p>
 <p>Satheesh Thurairajah</p>
 <p>Piranavam ThiruChelvan &lt;;,</p>
 <p>Dharmarajeswaran Dharmeehan &lt;;,</p>
 <p>Selvarajah Selvendra &lt;;,</p>
 <p>Lilantha Darshana &lt;;,</p>
 <p>Nadika Ranasinghe &lt;,;,</p>

View raw message