You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by sa...@apache.org on 2006/03/31 19:02:15 UTC
svn commit: r390460 [2/5] - in /webservices/axis2/site/c: ./ M0_5/
M0_5/images/ api/ docs/ docs/images/ images/ images/logos/ style/
Added: webservices/axis2/site/c/docs/developerguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/developerguide.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/developerguide.html (added)
+++ webservices/axis2/site/c/docs/developerguide.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,267 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C Developer Guide</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_Developer_Guide"></a><h2>Axis2/C Developer Guide</h2><p>Please send your feedback to developer mailing list: <a href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a> (Please
+remember to prefix the subject with [Axis2]). To subscribe to developer
+mailing lists see <a href="../mail-lists.html">here</a></p><div class="subsection"><a name="Content"></a><h3>Content</h3><p>This guide walks you through the following topics that might help you get
+familiar with the Axis2/C project and its development norms in quick time.</p><ul>
+ <li><a href="#Programming_Model">Programming model</a></li>
+ <li><a href="#Memory_Management">Memory management</a></li>
+ <li><a href="#Coding_Conventions">Coding conventions</a></li>
+ <li><a href="#Unit_and_System_Tests">Unit and System tests</a></li>
+</ul><p><a id="Programming_Model"></a></p></div><div class="subsection"><a name="Programming_Model"></a><h3>Programming Model</h3><p>Axis2/C programming model uses a pseudo object oriented model to achieve
+data hiding. The following example illustrates how this is done in Axis2/C.
+Each struct corresponds to the "class" concept in object oriented
+programming. Hence, each struct has its own header file, that exposes the API
+for that struct and a source file, that contains the functional
+implementation.</p><p>Operations associated with a struct are bundled into an operations struct,
+and the operations struct is exposed in the header file. The real
+implementation struct with the data fields is hidden from the user, and lives
+in the source file. To ease the user from using the complex syntax required
+by the use of the operations struct, macros are provided to access the
+functions associated with a given struct. Since the data is hidden, it is the
+usual practice to provide getter and setter methods for the data fields of
+the struct, in addition to the other processing functionality. Actual
+function implementations are mapped to the functions in the operations struct
+in the source file by means of function pointer assignments.</p><p>Here is a sample header file associated with the "foo" struct.</p><strong>/* axis2_ foo.h */</strong>
+ <div class="source"><pre>
+typedef struct axis2_foo_ops axis2_foo_ops_t;
+typedef struct axis2_foo axis2_foo_t;
+
+struct axis2_foo_ops
+{
+ void (AXIS2_CALL *bar)(axis2_foo_t *foo, axis2_env_t **env, void *data);
+ axis2_status_t (AXIS2_CALL *free)(axis2_foo_t *foo, axis2_env_t **env);
+};
+
+struct axis2_foo
+{
+ axis2_foo_ops_t *ops;
+}
+
+
+axis2_foo_t * axis2_foo_create(axis2_env_t **env);
+
+/* Macros are provided to access functions defined in the ops (operations structure)*/
+
+#define AXIS2_FOO_BAR(foo, data)\
+ ((foo)->ops->bar(data))
+#define AXIS2_FOO_FREE(foo, env)\
+ ((for)->ops->free(env, foo))
+
+</pre></div>
+ <p>The implementation file for "foo" struct is shown below.</p>
+ <div class="source"><pre>
+#include <axis2_foo.h>
+
+typedef struct axis2_foo_impl axis2_foo_impl_t;
+
+struct axis2_foo_impl
+{
+ axis2_foo_t foo;
+ my_type my_data; /*private data*/
+};
+
+/* Function Headers */
+
+void AXIS2_CALL axis2_foo_bar(void *data);
+axis2_status_t AXIS2_CALL axis2_foo_free(axis2_env_t **env, axis2_foo_t *foo);
+
+/* Function Implementation */
+axis2_foo_t * AXIS2_CALL axis2_foo_create(axis2_env_t **env)
+{
+ axis2_foo_impl_t * foo_impl = NULL;
+ /* create axis2_foo_t and initialize private data */
+
+ /* create ops structure of foo */
+
+ /* bind ops to functions */
+ foo_impl->foo.ops->bar = axis2_foo_bar;
+ foo_impl->foo.ops->free = axis2_foo_free;
+ return &(foo_impl->foo);
+}
+
+void AXIS2_CALL axis2_foo_bar(void *data)
+{
+ /* do something */
+}
+
+axis2_status_t AXIS2_CALL axis2_foo_free(axis2_env_t **env, axis2_foo_t *foo)
+{
+ /* do the dirty work of cleaning the allocated memory */
+}
+</pre></div>
+ <p><a id="Memory_Management"></a></p><p>If you had a closer look into the given sample above, you will see that
+almost all functions take a double pointer to the axis2_env struct. To learn
+more on environment used in Axis2/C, please have a look into the <a href="architecture_notes.html">architecture notes</a>.</p></div><div class="subsection"><a name="Memory_Management"></a><h3>Memory Management</h3><p>When writing services, as well as client programs, you have to ensure that
+you do proper memory management. You need to be aware of the parts of the
+memory you have allocated to deallocate in order to avoid memory leaks (and
+to avoid those nasty segmentation faults ;-) ).</p></div><div class="subsection"><a name="Memory_Management_Guidelines_for_Developing_Services"></a><h3>Memory Management Guidelines for Developing Services</h3><p>To understand, how the allocated memory is reclaimed, it is worth looking
+at the service skeleton interface which is defined in
+<strong>axis2_svc_skeleton.h</strong></p>
+ <div class="source"><pre>AXIS2_DECLARE_DATA struct axis2_svc_skeleton_ops
+{
+ int (AXIS2_CALL * free)(axis2_svc_skeleton_t *svc_skeli, axis2_env_t **env);
+ ...
+};
+
+AXIS2_DECLARE_DATA struct axis2_svc_skeleton
+{
+ axis2_svc_skeleton_ops_t *ops;
+ axis2_array_list_t *func_array;
+};
+
+</pre></div>
+ <p>The service skeleton implementation should implement the free function and
+attach that to the operations struct of axis2_svc_skeleton_t struct. This
+free function is called each time after web services request is served.</p><p>Let's try to understand this through an example.</p><p>Example: <b>Service skeleton implementation for math service.</b></p><p>The following code shows the implementation of math_free function which is
+to be attached to the ops of axis2_svc_skeleton_t struct. Usually the memory
+allocated for operations struct, function array and service skeleton struct
+are cleaned in this. You may clean additional memory here if you have
+allocated any specific memory blocks in math_create function or elsewhere
+depending on your implementation specifics.</p>
+ <div class="source"><pre>int AXIS2_CALL math_free(axis2_svc_skeleton_t *svc_skeleton, axis2_env_t **env)
+{
+ if(svc_skeleton->ops)
+ {
+ AXIS2_FREE((*env)->allocator, svc_skeleton->ops);
+ svc_skeleton->ops = NULL;
+ }
+ if(svc_skeleton->func_array)
+ {
+ AXIS2_ARRAY_LIST_FREE(svc_skeleton->func_array, env);
+ svc_skeleton->func_array = NULL;
+ }
+ if(svc_skeleton)
+ {
+ AXIS2_FREE((*env)->allocator, svc_skeleton);
+ svc_skeleton = NULL;
+ }
+ return AXIS2_SUCCESS;
+}
+
+</pre></div>
+ <p>In the axis2_math_create function you assign the function pointer of
+math_free function to the free function of the operations struct. As you can
+see, now the SOAP engine has a function reference to perform garbage
+collection after each service request.</p>
+ <div class="source"><pre>AXIS2_DECLARE(axis2_svc_skeleton_t *) axis2_math_create(axis2_env_t **env)
+{
+ axis2_svc_skeleton_t *svc_skeleton = NULL;
+ svc_skeleton = AXIS2_MALLOC((*env)->allocator, sizeof(axis2_svc_skeleton_t));
+
+ svc_skeleton->ops = AXIS2_MALLOC((*env)->allocator, sizeof(axis2_svc_skeleton_ops_t));
+
+
+ svc_skeleton->ops->free = math_free;
+ ...
+ return svc_skeleton;
+}
+
+</pre></div>
+ <p>SOAP engine frees the memory allocated for the axis2_om_node_t struct that
+is used to from the response SOAP message. However, it is the responsibility
+of the service developer to clean any additional memory allocated.</p></div><div class="subsection"><a name="Memory_management_guidelines_for_developing_clients"></a><h3>Memory management guidelines for developing clients</h3><p>
+Most of the memory allocated in the client side (including SOAP request and
+reply messges), should be cleaned in the client side itself. Memory allocated
+for properties are taken care of by the SOAP engine. SOAP engine reclaims the
+memory allocated for properties based on the scope (Request, Session or
+Application) that you set for each property. <a id="Coding_Conventions"></a></p></div><div class="subsection"><a name="Coding_Conventions"></a><h3>Coding Conventions</h3><p>Coding conventions used with the Axis2 project is listed in <a href="../coding_conventions.html">this</a> document.</p><p><a id="Unit_and_System_Tests"></a></p></div><div class="subsection"><a name="Unit_and_System_Tests"></a><h3>Unit and System Tests</h3></div><div class="subsection"><a name="Unit_Tests"></a><h3>Unit Tests</h3><p><a href="http://cutest.sourceforge.net/" class="externalLink" title="External Link">CuTest</a> library is used to
+write unit tests in Axis2/C.</p><p>You need to follow two steps to write a unit test for a module.</p><p>
+1. Add the unit test to the module's test suite.
+
+</p><p>2. Add the module's test suite to the main unit test suite.</p></div><div class="subsection"><a name="Step1:_Adding_a_unit_test_to_a_module_s_unit_test_suite"></a><h3>Step1: Adding a unit test to a module's unit test suite</h3><p>This section illustrates how to add a unit test case to the util module.
+Let's take for example the unit tests for axis2 stream. There are two files
+named util_stream_test.c/.h placed into modules/util/test folder. Here's a
+sample code written to test the operation axis2_stream_ops_read.</p>
+ <div class="source"><pre>#include "util_stream_test.h"
+
+void Testaxis2_stream_ops_read(CuTest *tc)
+{
+ char actual[10];
+ axis2_allocator_t *allocator = axis2_allocator_init(NULL);
+ axis2_env_t *env = axis2_environment_create(allocator,NULL, NULL, NULL, NULL);
+ axis2_stream_read(env->stream, actual, 10);
+ char *expected = strdup("aaaaaaaaa");
+ CuAssertStrEquals(tc, expected, actual);
+}
+
+</pre></div>
+ <p>The prototype of the function should be added to the header file. The test
+suite is defined in util_test.c. You need to add the above defined test case
+to the test suite as shown below.</p>
+ <div class="source"><pre>#include "util_test.h"
+#include <axis2_allocator.h>
+#include <axis2_environment.h>
+
+CuSuite* axis2_utilGetSuite()
+{
+ CuSuite* suite = CuSuiteNew();
+
+ SUITE_ADD_TEST(suite, Testaxis2_stream_ops_write);
+ SUITE_ADD_TEST(suite, Testaxis2_log_ops_write);
+ SUITE_ADD_TEST(suite, Testaxis2_hash_ops_get);
+ return suite;
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Step2:_Adding_the_Module_test_suite_to_the_Main_Unit_Test_Suite"></a><h3>Step2: Adding the Module test suite to the Main Unit Test Suite</h3><p>Now you need to add the Util module test suite to the main test suite.</p>
+ <div class="source"><pre>#include <CuTest.h>
+#include "../../util/test/util_test.h"
+#include "../../common/test/common_test.h"
+
+void RunAllTests(void)
+{
+ CuString *output = CuStringNew();
+ CuSuite* suite = CuSuiteNew();
+
+ CuSuiteAddSuite(suite, axis2_utilGetSuite());
+ CuSuiteAddSuite(suite, axis2_commonGetSuite());
+ CuSuiteRun(suite);
+ CuSuiteSummary(suite, output);
+ CuSuiteDetails(suite, output);
+ printf("%s\n", output->buffer);
+}
+
+int main(void)
+{
+ RunAllTests();
+ return 0;
+}
+
+</pre></div>
+ <p>You can either run only the unit tests written for the util module or run
+all the tests.</p></div><div class="subsection"><a name="System_Tests"></a><h3>System Tests</h3><p>For each module, system tests should be provided in
+modules/test/<module folder>. For each system test you need to add a
+new function and call it from the main method.</p><p>Example:</p><p>To test the OM module, you need to create a file named test_om.c under the
+directory modules/test/xml/om. A sample test_om.c might look like as
+follows.</p>
+ <div class="source"><pre>#include <axis2_om_stax_builder.h>
+#include <axis2_om_document.h>
+#include <axis2_om_node.h>
+#include <axis2_om_element.h>
+#include <axis2_om_text.h>
+#include <axis2_xml_reader.h>
+
+int test_om_build()
+{
+ axis2_xml_reader_t *reader = NULL;
+ axis2_om_node_t *node1 = NULL ,*node2 = NULL ,*node3 = NULL;
+ axis2_om_element_t *ele1=NULL,*ele2=NULL,*ele3 = NULL;
+ axis2_stax_om_builder_t *builder = NULL;
+ axis2_om_document_t *document = NULL;
+
+ ...
+}
+
+int main(void)
+{
+ test_om_build();
+ test_om_serialize();
+}
+
+
+</pre></div>
+ </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/images/OM005.gif
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/OM005.gif?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/OM005.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/archi006.jpg
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/archi006.jpg?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/archi006.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/arrow_left.gif
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/arrow_left.gif?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/arrow_left.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/arrow_right.gif
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/arrow_right.gif?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/arrow_right.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/binary_folder_structure.jpg
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/binary_folder_structure.jpg?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/binary_folder_structure.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/folder_structure.jpg
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/folder_structure.jpg?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/folder_structure.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/images/folder_structure_libxml2.jpg
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/images/folder_structure_libxml2.jpg?rev=390460&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/c/docs/images/folder_structure_libxml2.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis2/site/c/docs/index.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/index.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/index.html (added)
+++ webservices/axis2/site/c/docs/index.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,19 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C Documentation</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_Documentation"></a><h2>Axis2/C Documentation</h2><div class="subsection"><a name="Getting_Started"></a><h3>Getting Started</h3><ul>
+ <li><a href="installationguide.html">Installation Guide</a></li>
+ <li><a href="developerguide.html">Developer Guide</a></li>
+ <li><a href="userguide.html">User Guide</a></li>
+</ul><p>
+
+</p></div><div class="subsection"><a name="Additional_References"></a><h3>Additional References</h3><ul>
+ <li><a href="http://ws.apache.org/axis2/0_93/Axis2ArchitectureGuide.html" class="externalLink" title="External Link">
+Architecture Guide</a></li>
+ <li><a href="architecture_notes.html">C Specific Architecture Notes</a></li>
+ <li><a href="om_tutorial.html">OM Tutorial</a></li>
+ <li><a href="../coding_conventions.html">Coding Conventions in Axis2/C</a></li>
+</ul><p>
+</p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/installationguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/installationguide.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/installationguide.html (added)
+++ webservices/axis2/site/c/docs/installationguide.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,379 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2-C Installation Guide</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_Installation_Guide"></a><h2>Axis2/C Installation Guide</h2><p>This document will guide you on how to install Axis2/C and run the server
+and client samples on Linux and Microsoft Windows operating systems.</p><p>This release comes in two forms, source and binary. Instructions are given
+below to install using any of those two forms.</p><p>Please send your feedback to the developer mailing list: <a href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a> (please
+remember to prefix the subject with [Axis2]). To subscribe to developer
+mailing list see <a href="../mail-lists.html">here</a></p><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ <li><a href="#linux">Installing and running on Linux</a>
+ <ul>
+ <li><a href="#linux_binary">Using binary release</a></li>
+ <li><a href="#linux_source">Using source release</a></li>
+ </ul>
+ </li>
+ <li><a href="#win">Installing and running on Microsoft Windows (win32)</a>
+ <ul>
+ <li><a href="#win_binary">Using the binary release</a>
+ <ul>
+ <li><a href="#bin_req">Requirements</a></li>
+ <li><a href="#bin_binaries">Binaries in the release</a></li>
+ <li><a href="#bin_run">Running the binaries</a></li>
+ </ul>
+ </li>
+ <li><a href="#win_source">Using the source release</a>
+ <ul>
+ <li><a href="#src_req">Requirements</a></li>
+ <li><a href="#edit">Editing Configure.in file</a></li>
+ <li><a href="#src_compile">Compiling the source</a></li>
+ <li><a href="#src_run">Running the binaries</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#installing-apache2">Installing Apache2 Web Server integration module
+ (mod_axis2)</a>
+ <ul>
+ <li><a href="#building-apache2">Building mod_axis2 from source tree</a></li>
+ <li><a href="#deploying-apache2">Deploying in Apache2 Web Server</a></li>
+ </ul>
+ </li>
+</ul><p><a></a></p></div><div class="subsection"><a name="Installing_and_running_on_Linux"></a><h3>Installing and running on Linux</h3><p>This can be done using binary or source distributions</p><p>To get both the binary and source distributions working, you need libxml2,
+which can be downloaded from <a href="http://xmlsoft.org/downloads.html" class="externalLink" title="External Link">here</a>.</p><p>(NOTE: most Linux systems has libxml2 by default.)</p><p><a></a></p></div><div class="subsection"><a name="1__Using_binary_release"></a><h3>1. Using binary release</h3><p>The following steps need to be taken to install and run Axis2/C using
+binary distribution on Linux</p></div><div class="subsection"><a name="1__Extract_the_binary_tar_package_to_a_folder_"></a><h3>1. Extract the binary tar package to a folder.</h3><ul>
+ <li>Set AXIS2C_HOME environment variable pointing to the location where you
+ have extracted Axis2C</li>
+ <li>AXIS2C_HOME='/your_path_to_axis2c'</li>
+ <li>export AXIS2C_HOME
+ <p>Note: You will need to set AXIS2C_HOME only if you need to run axis2c
+ samples or tests. The reason is</p>
+ <p>that the samples and tests use the AXIS2C_HOME envioronment variable
+ to locate the repository path. To write your own</p>
+ <p>services or clients this would not be neccessary.</p>
+ </li>
+</ul></div><div class="subsection"><a name="2__Run_the_simple_axis_server:"></a><h3>2. Run the simple axis server:</h3><ul>
+ <li>To start the simple axis server on default port 9090, run the following
+ commands.
+ <ul>
+ <li>cd /your_path_to_axis2c/bin</li>
+ <li>./axis2_http_server</li>
+ </ul>
+ </li>
+ <li>To see the possible command line options run ./axis2_http_server -h</li>
+ <li>NOTE: If you run into shared lib problems, try setting the
+ LD_LIBRARY_PATH
+ <ul>
+ <li>export
+ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
+ </ul>
+ </li>
+</ul></div><div class="subsection"><a name="3__Run_the_sample_clients_in_a_new_shell"></a><h3>3. Run the sample clients in a new shell</h3><ul>
+ <li>cd /your_path_to_axis2c/bin/samples</li>
+ <li>to run client for echo service
+ <ul>
+ <li>./echo</li>
+ </ul>
+ </li>
+ <li>to run client for math service
+ <ul>
+ <li>./math</li>
+ </ul>
+ </li>
+ <li>To see the possible command line options for sample clients run them
+ with '-h' option</li>
+ <li>NOTE: If you run into shared lib problems, try setting the
+ LD_LIBRARY_PATH
+ <ul>
+ <li>export
+ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
+ </ul>
+ </li>
+</ul><p><a></a></p></div><div class="subsection"><a name="2__Using_source_release"></a><h3>2. Using source release</h3><p>The following steps need to be taken to install and run Axis2/C using
+source distribution on Linux</p><ol>
+ <li>Extract the source tar package to a folder.</li>
+ <li>Set AXIS2C_HOME environment variable pointing to the location where you
+ want to install Axis2C.
+ <ul>
+ <li>AXIS2C_HOME='/your_desired_path_to_axis2c_installation'</li>
+ <li>export AXIS2C_HOME</li>
+ </ul>
+ </li>
+ <li>Then go to the folder where you extracted the source
+ <ul>
+ <li>cd /your_path_to_axis2c_source</li>
+ </ul>
+ </li>
+ <li>Set parser location
+ <p>Include path and library path to parser should be set. For libxml2
+ this is automatically resolved by configure script.</p>
+ </li>
+ <li>Build the source
+ <ul>
+ <li>This can be done using the following command sequence:
+ <ul>
+ <li>./configure</li>
+ <li>make</li>
+ <li>make install</li>
+ </ul>
+ </li>
+ <li>use './configure --help' for possible command line options.</li>
+ <li>NOTE: If you don't provide a --prefix configure option, it will by
+ defaul install into /usr/local/axis2c folder.</li>
+ <li>If you need to get the samples working, you also need to build the
+ samples.
+ <p>To build samples:</p>
+ <ul>
+ <li>cd samples</li>
+ <li>./configure --prefix=${AXIS2C_HOME}</li>
+ <li>make</li>
+ <li>make install</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>Go to where you installed axis2c.</li>
+ <li>Start simple axis server
+ <ul>
+ <li>To start the simple axis server on port 9090 run the following
+ command lines
+ <ul>
+ <li>cd axis2c/bin</li>
+ <li>./axis2_http_server</li>
+ </ul>
+ </li>
+ <li>To see the possible command line options run ./axis2_http_server
+ -h</li>
+ </ul>
+ </li>
+ <li>Run the sample clients in a new shell using the following command lines
+ <ul>
+ <li>cd bin/samples</li>
+ <li>to run client for echo service
+ <ul>
+ <li>./echo</li>
+ </ul>
+ </li>
+ <li>to run client for math service
+ <ul>
+ <li>./math</li>
+ </ul>
+ </li>
+ <li>To see the possible command line options for sample clients run
+ them with '-h' option</li>
+ </ul>
+ </li>
+</ol><p><a></a></p></div><div class="subsection"><a name="Installing_and_running_on_Microsoft_Windows__win32_"></a><h3>Installing and running on Microsoft Windows (win32)</h3><p>This too can be done using either binary or source distributions</p><p>For both the binary and source distributions, you need libxml2 from <a href="http://xmlsoft.org/downloads.html" class="externalLink" title="External Link">here</a>.</p><p>(NOTE: most Linux systems has libxml2 by default. On Windows you need to
+download and install libxml2)</p><p><a></a></p></div><div class="subsection"><a name="1__Using_binary_release"></a><h3>1. Using binary release</h3><p><a></a></p></div><div class="subsection"><a name="Requirements"></a><h3>Requirements</h3><ul>
+ <li>The binaries shipped with this version is compiled with Microsoft
+ visual studio compiler (cl)</li>
+
+ <p>(Note: you can download Microsoft VSExpress2005 edition from Microsoft
+ web site and install it to run these binaries)</p>
+ <li>You also need the following dlls
+ <ul>
+ <li>libxml2.dll [http://www.xmlsoft.org - download the version >=
+ libxml2-2.6.20.win32]</li>
+ <li>iconv.dll [http://www.xmlsoft.org - download the version >=
+ iconv-1.9.1.win32]</li>
+ <li>zlib1.dll [http://www.xmlsoft.org - download the version >=
+ zlib-1.2.3.win32]</li>
+ </ul>
+ </li>
+</ul><p><a></a></p></div><div class="subsection"><a name="Binaries_in_the_release"></a><h3>Binaries in the release</h3><ul>
+ <li>Extract the binary distribution to a folder of your choice. (example:
+ C:\axis2c)</li>
+ <li>The C:\axis2c folder structure is as follows:</li>
+
+ <p><img alt="Figure: c:\axis2c Folder Structure" src="images/binary_folder_structure.jpg"></img></p>
+
+ <p><em>The above folders contain the following files:</em></p>
+ <ul>
+ <li>bin - server and other executables</li>
+ <li>bin\samples - client samples go here</li>
+ <li>lib - library modules</li>
+ <li>services - deployed services</li>
+ <li>modules - deployed modules</li>
+ <li>include - all include files of Axis2 C</li>
+ <li>logs - system and client logs are written to this folder</li>
+ </ul>
+ <li>Copy libxml2.dll, iconv.dll and zlib1.dll downloaded to
+ C:\axis2c\lib</li>
+</ul><p><a></a></p></div><div class="subsection"><a name="Running_the_binaries"></a><h3>Running the binaries</h3><ul>
+ <li>First you need to set couple of environment variables before you can
+ run the server and samples.
+ <ul>
+ <li>Set the varibale AXIS2C_HOME to the deploy folder (C:\axis2c)</li>
+ <li>Add the path to lib directory to PATH variable
+ (%AXIS2C_HOME%\lib)</li>
+ </ul>
+ </li>
+ <li>Now everything is set to run the server (C:\axis2c\bin\>
+ axis2_http_server.exe)</li>
+ <li>If the server is running successfully you should see the message
+ "Started Simple Axis2 HTTP Server..."</li>
+ <li>The log is by default created in %AXIS2C_HOME%\logs folder with the
+ name axis2.log.</li>
+ <li>(Note: you may provide command line options to change the default
+ behaviour. Use the command "axis2_http_server.exe -h" to learn about the
+ usage)</li>
+ <li>Now you can run any sample client located in %AXIS2C_HOME%\bin\samples\
+ <ul>
+ <li>Example: C:\axis2c\bin\samples\> echo.exe</li>
+ </ul>
+ </li>
+</ul><p><a></a></p></div><div class="subsection"><a name="2__Using_the_source_release_"></a><h3>2. Using the source release.</h3><p><a></a></p></div><div class="subsection"><a name="Requirements"></a><h3>Requirements</h3><ul>
+ <li>The makefile shipped with this version needs Microsoft visual studio
+ compiler (cl) and nmake build tool</li>
+
+ <p>(Note: you can download Microsoft VSExpress2005 edition and Platform SDK
+ from Microsoft web site. You will need to add the path to Platform SDK
+ Include and Lib folders to makefile)</p>
+ <li>You also need
+ <ul>
+ <li>libxml2 [http://www.xmlsoft.org - download the version >=
+ libxml2-2.6.20.win32]</li>
+ <li>iconv [http://www.xmlsoft.org - download the version >=
+ iconv-1.9.1.win32]</li>
+ <li>zlib [http://www.xmlsoft.org - download the version >=
+ zlib-1.2.3.win32]</li>
+ </ul>
+ </li>
+</ul><p><a></a></p></div><div class="subsection"><a name="Editing_configure_in_file"></a><h3>Editing configure.in file</h3><ul>
+ <li>The default paths for libxml2 and iconv are speceficed in configure.in.
+ <ul>
+ <li>Example:Default location for libxml2 is C:\libxml2</li>
+ </ul>
+ </li>
+ <li>You can either extract libxml2 to this folder, in which case folder
+ structure for C:\libxml2 should look like the following.</li>
+
+ <p><img alt="Figure: C:\libxml2 Folder Structure" src="images/folder_structure_libxml2.jpg"></img></p>
+
+ <p>Or extract to whatever place of your choice and edit the configure.in
+ accordingly.</p>
+ <li>You need to have zlib1.dll in a library path. You may copy this dll to
+ libxml2/lib.</li>
+</ul><p><a></a></p></div><div class="subsection"><a name="Compiling_the_source_"></a><h3>Compiling the source.</h3><p>The following steps will take you through the source compilation</p><ul>
+ <li>Extract the source distribution to a folder of your choice. (Example:
+ C:\axis2c)</li>
+ <li>Open a DOS shell</li>
+ <li>cd C:\axis2c\build\win32</li>
+ <li>to access .Net tools, run
+ <ul>
+ <li>C:\axis2c\build\win32> vcvars32.bat</li>
+ </ul>
+ <p>(Note: You may need to set the PATH environment variable to
+ vcvars32.bat if windows complaints that it cannot find this bat)</p>
+ </li>
+ <li>build the system and create a directory named deploy under build
+ directory:
+ <ul>
+ <li>C:\axis2c\build\win32>nmake install</li>
+ </ul>
+ </li>
+ <li>The deploy folder structure is as follows:</li>
+
+ <p><img alt="Figure: deploy Folder Structure" src="images/folder_structure.jpg"></img></p>
+
+ <p><em>The above folders contain the following files:</em></p>
+ <ul>
+ <li>bin - server and other executables</li>
+ <li>bin\samples - client samples</li>
+ <li>lib - library modules</li>
+ <li>services - deployed services</li>
+ <li>modules - deployed modules</li>
+ <li>include - all include files of Axis2 C</li>
+ <li>logs - system and client logs are written to this folder</li>
+ </ul>
+</ul><p><a></a></p></div><div class="subsection"><a name="Running_the_binaries"></a><h3>Running the binaries</h3><ul>
+ <li>You need to set couple of environment variables before you can run the
+ server and samples.
+ <ul>
+ <li>Set the variable AXIS2C_HOME to the deploy folder
+ (C:\axis2c\build\deploy)</li>
+ <li>Add the path to lib directory to PATH variable
+ (%AXIS2C_HOME%\lib)</li>
+ <li>Copy libxml2.dll, iconv.dll and zlib1.dll to axis2c lib folder
+ (%AXIS2C_HOME%\lib)</li>
+ </ul>
+ </li>
+ <li>Now run the server - C:\axis2c\build\deploy\bin>
+ axis2_http_server.exe</li>
+ <li>If server is running successfully you should see the message "Started
+ Simple Axis2 HTTP Server..."</li>
+ <li>The log is by default created under %AXIS2C_HOME%\logs folder with the
+ name axis2.log.</li>
+ <li>(Note: you may provide command line options to change the default
+ behaviour. Use the command "axis2_http_server.exe -h" to learn about the
+ usage)</li>
+ <li>Now you can run any sample client deployed under
+ %AXIS2C_HOME%\bin\samples\
+ <ul>
+ <li>Example: C:\axis2c\build\deploy\bin\samples> echo.exe</li>
+ </ul>
+ </li>
+</ul><p><a id="installing-apache2"></a></p></div><div class="subsection"><a name="3__Installing_Apache2_Web_Server_integration_module__mod_axis2__"></a><h3>3. Installing Apache2 Web Server integration module (mod_axis2).</h3></div><div class="subsection"><a name="3_1_Building_mod_axis2_from_source_tree"></a><h3>3.1 Building mod_axis2 from source tree</h3></div><div class="subsection"><a name="3_1_1_On_Linux_Platform"></a><h3>3.1.1 On Linux Platform</h3><ul>
+ <li>Provide the apache2 include files location as configure option
+ ./configure --with-apache2="<apache2 include files location>"
+ [other configure options] - Some apache2 distributions install APR
+ (Apache Portable Runtime) include files in a seperate location which is
+ requred to build mod_axis2. In that case use
+ <p>./configure --with-apache2="<apache2 include files location>"
+ --with-apr="<apr include files location>" [other configure
+ options]</p>
+ </li>
+ <li>Then build the source tree<br></br>
+ make<br></br>
+ make install<br></br>
+ - This will install mod_axis2.so into your
+ "<your_path_to_axis2c>/lib"</li>
+</ul></div><div class="subsection"><a name="3_1_2_On_Win32_platform"></a><h3>3.1.2 On Win32 platform</h3><ul>
+ <li>Provide the apache2 location in configure.in file in
+ APACHE_INSTALL_DIR<br></br>
+ eg : APACHE_INSTALL_DIR = E:\Apache</li>
+ <li>After compiling the sources (as described in section 2) build the
+ mod_axis2.dll by issuing the command "nmake axis2_apache_module".</li>
+ <li>This will build the mod_axis2.dll and copy it to %AXIS2C_HOME%\lib
+ directory.<br></br>
+ eg: C:\axis2c\build\deploy\lib</li>
+</ul></div><div class="subsection"><a name="3_2_Deploying_in_Apache2_Web_Server"></a><h3>3.2 Deploying in Apache2 Web Server</h3><p><b>Note: To do the following tasks you might need super user privileges in
+your machine.</b></p><ul>
+ <li>Copy the mod_axis2 (libmod_axis2.so.0.0.0 on Linux and mod_axis2.dll in
+ Windows) to "<apache2 modules directory>" (eg:
+ /usr/lib/apache2/modules in Linux or C:\Apache2\modules in Windows) as
+ mod_axis2.so
+ <p>eg: cp $AXIS2C_HOME/lib/libmod_axis2.so.0.0.0
+ /usr/lib/apache2/modules/mod_axis2.so<br></br>
+ copy C:\axis2c\build\deploy\lib\mod_axis2.dll
+ C:\Apache2\modules\mod_axis2.so</p>
+ </li>
+ <li>Edit the Apache2's configuration file (generally httpd.conf) and add
+ the following directive
+ <pre> LoadModule axis2_module <apache2 modules directory>/mod_axis2.so
+ <Location /axis2>
+ SetHandler axis2_module
+ RepoPath <axis2 repository path>
+ LogFile <axis2 log file path>
+ Axis2LogLevel LOG_LEVEL
+ </Location>
+ </pre>
+ <p>LOG_LEVEL can be one of following <br></br>
+ AXIS2_LOG_LEVEL_CRITICAL - Log critical errors only <br></br>
+ AXIS2_LOG_LEVEL_ERROR - Log errors critical errors <br></br>
+ AXIS2_LOG_LEVEL_WARNING - Log warnings and above <br></br>
+ AXIS2_LOG_LEVEL_INFO - Log info and above <br></br>
+ AXIS2_LOG_LEVEL_DEBUG - Log debug and above (default) <br></br>
+ AXIS2_LOG_LEVEL_TRACE - Log trace messages</p>
+ </li>
+ <li>Use forward slashes "/" for path seperators in <apache2 modules
+ directory>, <axis2 repository path> and <axis2 log file
+ path></li>
+ <li>Make sure that the apache2 user has correct permissions to above
+ paths<br></br>
+ - Read permission to the repository<br></br>
+ - Write permission to the log file</li>
+ <li>Restart apache2 and test whether mod_axis2 module is loaded by typing
+ the URL http://localhost/axis2/services</li>
+</ul></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/om_tutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/om_tutorial.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/om_tutorial.html (added)
+++ webservices/axis2/site/c/docs/om_tutorial.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,578 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C OM Tutorial</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_OM_Tutorial"></a><h2>Axis2/C OM Tutorial</h2><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li><a href="#Introduction">Introduction</a>
+ <ul>
+ <li><a href="#What_is_OM">What is OM</a></li>
+ <li><a href="#For_Whom_is_This_Tutorial">For Whom is This
+ Tutorial</a></li>
+ <li><a href="#What_is_Pull_Parsing">What is Pull Parsing</a></li>
+ <li><a href="#Features_of_OM">Features of OM</a></li>
+ <li><a href="#Where_Does_SOAP_Come_into_Play_">Where Does SOAP Come
+ into Play?</a></li>
+ </ul>
+ </li>
+ <li><a href="#Working_with_OM">Working with OM</a>
+ <ul>
+ <li><a href="#Creation">Creation</a></li>
+ <li><a href="#Addition_and_Detaching_of_Nodes">Addition and Detaching
+ of Nodes</a></li>
+ <li><a href="#Traversing">Traversing</a></li>
+ </ul>
+ </li>
+</ul><p><a id="Introduction"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p><a id="What_is_OM"></a></p></div><div class="subsection"><a name="What_is_OM_"></a><h3>What is OM?</h3><p>OM stands for Object Model (a.k.a AXIOM - AXis Object Model) and refers to
+the XML infoset model that is developed for Axis 2. XML infoset refers to the
+information included inside the XML. For programmatical manipulation it is
+convenient to have a representation of this XML infoset in a language
+specific manner. DOM and JDOM are two such XML models. OM is conceptually
+similar to such an XML model by its external behavior but deep down it is
+very much different.</p><p>The objective of this tutorial is to introduce the basics of OM C and
+explain best practices while using OM.</p><p>AXIOM C is a C implementation of AXIOM java. We have tried to get almost
+the same kind of API in C.</p><p><a id="For_Whom_is_This_Tutorial"></a></p></div><div class="subsection"><a name="For_whom_is_this_Tutorial_"></a><h3>For whom is this Tutorial?</h3><p>This tutorial can be used by anybody who is interested and wants to go
+deeper in to OM C. Knowledge in similar object models such as DOM will be
+quite helpful in understanding OM but such knowledge is not assumed. Several
+links are listed in the appendix/ links section that will help understand the
+basics of XML.</p><p><a id="What_is_Pull_Parsing"></a></p></div><div class="subsection"><a name="What_is_Pull_Parsing__"></a><h3>What is Pull Parsing ?</h3><p>
+Pull parsing is a new trend in XML processing. The previously popular XML
+processing frameworks such as SAX and DOM were "push-based" which means the
+control of the parsing was with the parser itself. This approach is fine and
+easy to use but it is not efficient in handling large XML documents since a
+complete memory model will be generated in the memory. Pull parsing inverts
+the control and hence the parser only proceeds at the users command. The user
+can decide to store or discard events generated from the parser. OM is based
+on pull parsing. To learn more about XML pull parsing see the <a href="http://www.bearcave.com/software/java/xml/xmlpull.html" class="externalLink" title="External Link">XML pull
+parsing introduction</a>. <a id="Features_of_OM"></a></p></div><div class="subsection"><a name="Features_of_OM"></a><h3>Features of OM</h3><p>OM is a lightweight, differed built XML info set representation based on
+StAX API derived form (<a href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/" class="externalLink" title="External Link">JSR
+173</a>), which is the standard streaming pull parser API. OM can be
+manipulated as flexibly as any other object model (Such as <a href="http://www.jdom.org/" class="externalLink" title="External Link">JDOM</a>), but underneath the objects will be
+created only when they are absolutely required. This leads to much less
+memory intensive programming. Following is a short feature overview of OM.</p><ul>
+ <li>Lightweight: OM is specifically targeted to be lightweight. This is
+ achieved by reducing the depth of the hierarchy, number of methods and
+ the attributes enclosed in the objects. This makes the objects less
+ memory intensive.</li>
+ <li>Differed building: By far this is the most important feature of OM. The
+ objects are not made unless a need arises for them. This passes the
+ control of building over to the object model itself rather than an
+ external builder.</li>
+ <li>Pull based: For a differed building mechanism a pull based parser is
+ required. OM is based on StAX, the standard pull parser API.
+ <p>Since different XML parsers offer different kinds of pull parser APIs
+ we define an API derived from StAX. That API is defined in
+ axis2_xml_reader.h , similarly we define an xml writer api in
+ axis2_xml_writer.h. These two APIs work as an abstarction layer between
+ any XML parser and OM. So any parser that is going to be used for OM
+ should implement the axis2_xml_reader API and axis2_xml_writer API using
+ a wrapper layer.</p>
+ <p>Currenly we use Libxml2 as our default XML parser.</p>
+ </li>
+</ul><p>
+
+
+</p><p class="img"><img alt="" src="images/archi006.jpg" class="img" width="490" height="282"></img></p><p>
+
+</p><p>OM Builder wraps the raw xml character stream through the axis2_xml_reader
+API. Hence the complexities of the pull event stream is covered</p><p><a id="Where_Does_SOAP_Come_into_Play?"></a></p></div><div class="subsection"><a name="Where_Does_SOAP_Come_into_Play_"></a><h3>Where Does SOAP Come into Play?</h3><p>In a nutshell SOAP is a information exchange protocol based on XML. SOAP
+has a defined set of XML elements that should be used in messages. Since Axis
+is a "SOAP Engine" and OM is built for Axis, A SOAP specific API was
+implemented on top of OM.We have defined a number of structs to represent
+SOAP constructs like Envelope etc.. These structs wraps general OM
+structures. See <a href="http://www.w3schools.com/SOAP/soap_intro.asp" class="externalLink" title="External Link">here</a> to learn more
+about SOAP.</p><p>
+<a id="Working_with_OM"></a></p></div><div class="subsection"><a name="Working_with_OM"></a><h3>Working with OM</h3><p><a id="Creation">Axis2c environment</a></p><p>Before starting the discussion on om, it is necessary to get a good
+understanding of the basics of axis2c. Axis2c is designed to be plugble to
+any system written in C or C++ and therefore axis2 has abstracted the
+functionalities that differ from system to system in to a structure
+"axis2_env_t" which we refer to as axis2 environment . The environment holds
+axis2_allocater_t [ used for memory allocation/deallocation ] , axis2_error_t
+[ error reporting mechanism ] axis2_log_t [ logging mechanism ] and
+axis2_thread_t [threading mechnism ]. axis2_allocator_t has function pointers
+to malloc, realloc and free functions and all memory allocation and
+deallocation is done using the allocator. So by pluging in a different
+allocator, a user can make the entire Axis2 system to use different memory
+management functions.</p><p>How to create the axis2 environment</p><p><b>creating the allocator</b></p><p>axis2_allocator_t *allocator = NULL;</p><p>allocator = axis2_allocator_init(NULL);</p><p></p><p>We parse NULL to the above function to use the default allocator. Then the
+allocators function pointers point to malloc, realloc and free functons. If
+you have your own allocator structure, you may pass it instead.</p><p>Convinent macros are defined to use allocator functions as follows (refer
+to axis2_allocator.h for more information).</p><p>AXIS2_MALLOC , AXIS2_REALLOC and AXIS2_FREE .</p><p>In a similar fashion, you can create the error and log structures.</p><p>axis2_log_t *log = NULL;</p><p>axis2_error_t *error = NULL;</p><p>log = axis2_log_create(allocator, NULL, NULL);</p><p>log = axis2_log_create(allocator, NULL, "mylog.log");</p><p>Now we can create the environment by parsing the allocator, error and log
+to axis2_env_create_with_error_log() function.</p><p>axis2_env_t *env = NULL;</p><p>env = axis2_env_create_with_error_log(allocator, error, log);</p><p></p><p>Apart from the above abstraction , all other library functions used are
+ANSI C complient. Further, platform dependent funtions are also
+abstracted.</p><p>As a rule of thumb, all "create" functions take a double pointer to the
+environment as its first argument and all other functions take pointer to
+'this' struct as the first argument and a double pointer to environment as
+the second argument. (Please refer to our coding convention page to learn
+more about this)</p><p>eg.</p><p>axis2_om_node_t *node = NULL;</p><p>axis2_om_node_t *child = NULL;</p><p>node = axis2_om_node_create(env);</p><p>Note that 'env' is a double pointer to the environment struct.</p><p>child = AXIS2_OM_NODE_GET_FIRST_CHILD(node, env);</p><p>Note that we are parsing the node (pointer to om_node_t ) as the first
+argument and double pointer to environment.</p><p></p><p>All functions return a pointer to a struct or a status code [
+AXIS2_SUCCESS , AXIS2_FAILURE]. So if NULL is returned by a function</p><p>it is either because there is nothing to return or an error has
+occured.</p></div><div class="subsection"><a name="Creation"></a><h3>Creation</h3><p>Creation is the first and foremost action when using an Object
+representation. This part explains how OM can be built from either an
+existing document or programmatically. OM provides a notion of a builder to
+create objects. Since OM is tightly bound to StAX, a StAX compliant reader
+should be created first with the desired input stream.</p><p>In our OM implementation we define a struct 'axis2_om_node_t' which acts
+as the container of the other structs and it maintains the links that form
+the Link List OM in C.</p><p>So to traverse the structure the functions defined in axis2_om_node.h must
+be used. To access xml information, the 'data element' struct stored in
+axis2_om_node_t must be obtained using the AXIS2_OM_NODE_GET_DATA_ELEMENT
+macro. The type of the struct stored in the 'axis2_om_node_t' struct can be
+obtained by AXIS2_OM_NODE_GET_NODE_TYPE macro. When we create
+axis2_om_element_t , axis2_om_text_t etc .., it is required to parse a double
+pointer to the node struct as the last parameter of the create function so
+that the correponding node struct can be referenced using that pointer.</p><p>Ex.</p><p>axis2_om_node_t *my_node = NULL;</p><p>axis2_om_element_t *my_ele = NULL;</p><p>my_ele = axis2_om_element_create(env, NULL, "MY_ELEMENT", NULL,
+&my_node);</p><p>Now if we call AXIS2_OM_NODE_GET_NODE_TYPE macro on 'my_node' pointer we
+will get the value as AXIS2_OM_ELEMENT .</p><div>
+<p><b>Code Listing 1</b></p>
+</div>
+ <div class="source"><pre>
+axis2_xml_reader_t *xml_reader = NULL;
+axis2_om_stax_builder_t *om_builder = NULL;
+axis2_soap_builder_t *soap_builder = NULL;
+axis2_soap_envelope_t *soap_envelope = NULL;
+
+axis2_xml_reader_t *xml_reader = axis2_xml_reader_create_for_file(env, "test_soap.xml",NULL);
+
+om_builder = axis2_om_stax_builder_create(env, xml_reader);
+
+soap_builder = axis2_soap_builder_create(env, om_builder , AXIS2_SOAP_ENVELOPE_NAMESPACE_URI);
+
+soap_envelope = AXIS2_SOAP_BUILDER_GET_SOAP_ENVELOPE(soap_builder, env);
+</pre></div>
+ <br></br><p>As the example shows, creating an OM from xml_reader is pretty straight
+forward. However elements and nodes can be created programmatically to modify
+the structure as well. Currently OM has two builders, namely the
+axis2_om_stax_builder_t and the axis2_soap_builder_t. These builders provide
+the necessary information to the XML info set model to build itself.</p><div>
+<p><b>Code Listing 2</b></p>
+</div><p class="img-title"><b></b></p>
+ <div class="source"><pre>axis2_om_namespace_t *ns1 = NULL;
+axis2_om_namespace_t *ns2 = NULL;
+
+axis2_om_element_t* root_ele = NULL;
+axis2_om_node_t* root_ele_node = NULL;
+
+axis2_om_element_t *ele1 = NULL;
+axis2_om_node_t *ele1_node = NULL;
+
+ns1 = axis2_om_namespace_create(env, "bar", "x");
+ns2 = axis2_om_namespace_create(env, "bar1", "y");
+
+
+root_ele = axis2_om_element_create(env, NULL, "root", ns1, &root_ele_node);
+ele1_node = axis2_om_element_create(env, root_node, "foo1", ns2, &ele1_node);
+
+</pre></div>
+ <p>Several differences exist between a programmatically created
+axis2_om_node_t and a conventionally built axis2_om_node_t. The most
+important difference is that the latter will have a pointer to its builder,
+where as the former does not have that information. As stated earlier in this
+tutorial, since the OM is built as and when required, each and every
+axis2_om_node_t struct should have a reference to its builder. If this
+information is not available, it is due to the struct being created without a
+builder.</p><p></p><p>The SOAP struct hierarchy is made in the most natural way for a
+programmer. It acts as a wrapper layer on top of OM implementation. The SOAP
+structs wraps the correspoding om_node_t structs to store information in
+xml.</p><p>
+<a id="Addition_and_Detaching_of_Nodes"></a></p></div><div class="subsection"><a name="Addition_and_Detaching_of_Nodes"></a><h3>Addition and Detaching of Nodes</h3><p>Addition and removal methods are defined in the axis2_om_node.h header.
+The following are the most important in adding nodes.</p><div>
+<p><b>Code Listing 3</b></p>
+</div><p>Add child operation</p>
+ <div class="source"><pre>axis2_status_t
+axis2_om_node_add_child( axis2_om_node_t *om_node,
+ axis2_env_t **env,
+ axis2_om_node_t *child_node);
+
+</pre></div>
+ <p>Detach operation</p>
+ <div class="source"><pre>axis2_om_node_t*
+axis2_om_node_detach (axis2_om_node_t *om_node,
+ axis2_env_t **env);
+
+</pre></div>
+ <p>The detach operation resets the links and remove a node from om
+structure.</p><p></p><p>This code segment shows how the addition takes place. Note that it is
+related to the code segment shown in the creation section.</p><div>
+<p><b>Code Listing 4</b></p>
+</div>
+ <div class="source"><pre>axis2_om_node_t *foo_node = NULL;
+axis2_om_element_t *foo_ele = NULL;
+axis2_om_node_t *bar_node = NULL;
+axis2_om_element_t *bar_ele = NULL;
+
+foo_ele = axis2_om_element_create(env, NULL, "FOO", NULL, &foo_node);
+bar_ele = axis2_om_element_create(env, NULL, "BAR", NULL. &bar_node);
+
+</pre></div>
+ <p>Now if we want to make 'BAR' element, a child of 'FOO' element we can use
+add_child MACRO.</p>
+ <div class="source"><pre> AXIS2_OM_NODE_ADD_CHILD(foo_node, env, bar_node);
+
+</pre></div>
+ <p>Or we can parse the foo_node as the parent node at the time of creating to
+bar_ele as follows.</p>
+ <div class="source"><pre> bar_ele = axis2_om_element_create(env, foo_node, "BAR", NULL, &bar_node);
+</pre></div>
+ <ul>
+ <li>add_child function will always add the child as the first child of the
+ parent.</li>
+ <li><p>A given node can be removed from the tree by calling the detach()
+ method. A node can also be removed from the tree by calling the remove
+ method of the returned iterator which will also call the detach method of
+ the particular node internally.</p>
+ </li>
+ <li>Namespaces are a tricky part of any XML object model and is the same in
+ OM. However the interface to the namespace have been made very simple.
+ axis2_om_namespace_t * is the struct that represents a namespace and we
+ do not have setter functions. This makes the axis2_om_namespace
+ immutable.</li>
+</ul><p>Following are the important methods available in axis2_om_element to
+handle namespaces.</p><div>
+<p><b>Code Listing 5</b></p>
+</div>
+ <div class="source"><pre>axis2_om_namespace_t*
+axis2_om_element_declare_namespace(axis2_om_element_t *om_ele,
+ axis2_env_t **env,
+ axis2_om_node_t *om_node,
+ axis2_om_namespace_t *om_ns);
+
+axis2_om_namespace_t*
+axis2_om_element_find_namespace(axis2_om_element_t *om_ele,
+ axis2_env_t **env,
+ axis2_om_node_t *om_node,
+ axis2_char_t *uri,
+ axis2_char_t *prefix);
+
+axis2_om_namespace_t*
+axis2_om_element_find_declared_namespace(axis2_om_element_t *om_element,
+ axis2_env_t **env,
+ axis2_char_t *uri,
+ axis2_char_t *prefix);
+
+axis2_status_t
+axis2_om_element_set_namespace(axis2_om_element_t *om_element,
+ axis2_env_t **env,
+ axis2_namespace_t *ns,
+ axis2_om_node_t *element_node);
+
+</pre></div>
+ <p>An om_element has a namespace list [declared namespaces] and a pointer to
+its own namespace if one exists.</p><p>The declare_namespace function is straight forward. It adds a namespace to
+namespace declarations section. Note that a namespace declaration that is
+already added will not be added twice.</p><p>find_namespace is a very handy method to locate a namespace higher up the
+tree. It searches for a matching namespace in its own declarations section
+and jumps to the parent if it's not found. The search progresses up the tree
+until a matching namespace is found or the root has been reached.</p><p>find_declared_namespace can be used to search for a namespace in the
+current element's namespace declarations section.</p><p>set_namespace an om_elements own namespace , [ Note that an element's own
+namespace should be declared in its own namespace declarations section or its
+one of its parent element. ] This method first searches for a matching
+namespace using find_namespace and if a matching namespace is not found
+anamespace is declared to this om_element's namespace declarations section
+before seting the own namespace reference.</p><p>The following simple code segment shows how the namespaces are dealt with
+in OM</p><div>
+<p><b>Code Listing 6</b></p>
+</div>
+ <div class="source"><pre>axis2_om_namespace_t *ns1 = NULL;
+axis2_om_namespace_t *ns2 = NULL;
+axis2_om_namespace_t *ns3 = NULL;
+
+axis2_om_node_t *root_node = NULL;
+axis2_om_element_t *root_ele = NULL;
+
+axis2_om_node_t *ele1_node = NULL;
+axis2_om_element_t *ele1 = NULL;
+
+axis2_om_node_t *text_node = NULL;
+axis2_om_text_t *om_text = NULL;
+
+ns1 = axis2_om_namespace_create(env, "bar", "x");
+ns2 = axis2_om_namespace_create(env, "bar1", "y");
+
+root_ele = axis2_om_element_create(env, NULL , "root", ns1, &root_node);
+ele1 = axis2_om_element_create(env, root_node, "foo", ns2, &ele1_node);
+om_text = axis2_om_text_create(env, ele1_node, "blah", &text_node);
+
+</pre></div>
+ <p>Serilization of the root element produces the following XML</p>
+ <div class="source"><pre><x:root xmlns:x="bar">
+ <y:foo xmlns:y="bar1">
+ blah
+ </y:foo>
+</x:root>
+</pre></div>
+ <p><a id="Traversing"></a></p><p>if we want to produce</p>
+ <div class="source"><pre><x:foo xmlns:x="bar" xmlns:y="bar1">Test</x:foo>
+
+</pre></div>
+ <p>we can use set_namespace and declare namespace functions as follows</p>
+ <div class="source"><pre>axis2_om_node_t *foo_node = NULL;
+axis2_om_element_t *foo_ele = NULL;
+axis2_om_namespace_t *ns1 = NULL;
+axis2_om_namespace_t *ns2 = NULL;
+
+foo_ele = axis2_om_element_create(env, NULL,"foo" ,NULL, &foo_node);
+
+ns1 = axis2_om_namespace_create(env, "bar", "x");
+
+ns2 = axis2_om_namespace_create(env, "bar1","y");
+
+AXIS2_OM_ELEMENT_SET_NAMESPACE(foo_ele, env, ns1, foo_node);
+
+AXIS2_OM_ELEMENT_DECLARE_NAMESPACE(foo_ele, env, ns2, foo_node);
+
+AXIS2_OM_ELEMENT_SET_TEXT(foo_ele, env, "Test", &foo_node);
+
+</pre></div>
+ </div><div class="subsection"><a name="Traversing"></a><h3>Traversing</h3><p>Traversing the OM structure can be done by obtaining an iterator struct.
+You can either call the appropriate function on OM element or create the
+iterator manually. OM C offers three iterators to traverse the OM structure.
+They are</p><ul>
+ <li>axis2_om_children_iterator_t</li>
+ <li>axis2_om_child_element_iterator_t</li>
+ <li>axis2_om_children_qname_iterator_t</li>
+</ul><p>The Iterator supports the 'OM way' of accessing elements and is more
+convenient than a list for sequential access. The following code sample shows
+how the children can be accessed. The children can be of type AXIS2_OM_TEXT
+or AXIS2_OM_ELEMENT.</p><div>
+<p><b>Code Listing 7</b></p>
+</div>
+ <div class="source"><pre>axis2_om_children_iterator_t *children_iter = NULL;
+children_iter = AXIS2_OM_ELEMENT_GET_CHILDREN(om_ele, env, om_node);
+if(NULL != children_iter )
+{
+ while(AXIS2_OM_CHILDREN_ITERATOR_HAS_NEXT(children_iter, env))
+ {
+ axis2_om_node_t *node = NULL;
+ node = AXIS2_OM_CHILDREN_ITERATOR_NEXT(children_iter, env);
+ if(NULL != node)
+ {
+ if(AXIS2_OM_NODE_GET_NODE_TYPE(node, env) == AXIS2_OM_ELEMENT)
+ {
+ /** any processing */
+ }
+ }
+
+ }
+}
+
+</pre></div>
+ <p>Apart from this, every axis2_om_node_t struct has links to its siblings.
+If a thorough navigation is needed the AXIS2_OM_NODE_GET_NEXT_SIBLING() and
+AXIS2_OM_NODE_GET_PREVIOUS_SIBLING() macros can be used. A restrictive set
+can be chosen by using AXIS2_OM_ELEMENT_XXX_WITH_QNAME() methods. The
+AXIS2_OM_ELEMENT_GET_FIRST_CHILD_WITH_QNAME() method returns the first child
+that matches the given axis2_qname_t and
+AXIS2_OM_ELEMENT_GET_CHILDREN_WITH_QNAME() returns
+axis2_om_children_qname_iterator_t which can be used to travese all the
+matching children. The advantage of these iterators are that they won't build
+the whole object structure at once; it builds only what is required.</p><p>
+
+<table class="bodyTable"><tbody>
+ <tr class="b"><td><img src="images/OM005.gif" alt="" width="35" height="57"></img></td><td class="special-td">All iterator implementations internally stay one
+ step ahead of their apparent location to provide the correct value
+ for the HAS_NEXT() function . This hidden advancement can build
+ elements that are not intended to be built at all.</td><td></td></tr>
+ </tbody></table>
+
+</p><p><b>Serialization</b></p><p>OM can be serialized using AXIS2_OM_NODE_SERIALIZE macro .The
+serialization uses axis2_xml_writer.h and axis2_om_output.h APIs.</p><p>Here is an example that shows how to write the output to the console, (We
+serialize the SOAP envelope created in code listing 1).</p><div>
+<p><b>Code Listing 8</b></p>
+</div>
+ <div class="source"><pre>axis2_xml_writer_t *xml_writer = NULL;
+axis2_om_output_t *om_output = NULL;
+axis2_char_t *buffer = NULL;
+
+..............
+
+xml_writer = axis2_xml_writer_create(env, NULL, 0, 0);
+om_output = axis2_om_output_create(env, xml_writer);
+
+AXIS2_SOAP_ENVELOPE_SERIALIZE(envelope, env, om_output);
+buffer = AXIS2_XML_WRITER_GET_XML(xml_writer, env);
+printf("%s ", buffer);
+
+</pre></div>
+ <p>An easy way to serialize is to use the to_string function in om_element</p><p><b>Code Listing 9</b></p>
+ <div class="source"><pre>axis2_char_t *xml_output = NULL;
+axis2_om_node_t *foo_node = NULL;
+axis2_om_element_t *foo_ele = NULL;
+axis2_om_namespace_t* ns = NULL;
+
+ns = axis2_om_namespace_create(env, "bar","x");
+
+foo_ele = axis2_om_element_create(env, NULL, "foo", ns, &foo_node);
+
+AXIS2_OM_ELEMENT_SET_TEXT(foo_ele, env, "EASY SERAILIZATION", foo_node);
+
+xml_output = AXIS2_OM_ELEMENT_TO_STRING(foo_ele, env, foo_node);
+
+printf("%s", xml_output);
+AXIS2_FREE((*env)->allocator, xml_output);
+
+</pre></div>
+ <p>Note that freing the returned buffer is users responsibility</p><p></p><p><b>Using axis2_xml_reader and axis2_xml_writer</b></p><p>axis2_xml_reader provides three create functions that and can be used for
+different xml input sources.</p><p>axis2_xml_reader_create_for_file() functon can be used to read from a
+file.</p><p>axis2_xml_reader_create_for_memory uses a user defined callback function
+to pull xml.</p><p>axis2_xml_reader_create_for_buffer can be used to read from an xml string
+that is in a character buffer.</p><p>Similarly xml_writer provides two create functions,</p><p>axis2_xml_writer_create_for_file can be used to write to a file.</p><p>axis2_xml_writer_create_for_memory can be used to write to an internal
+memory buffer and obtain the xml string to a charcater buffer as</p><p>the output. Please refer to axis2_xml_reader.h and axis2_xml_writer.h for
+more information.</p><p><b>How to avoid memory leaks and double frees when using om</b></p><p>You have to be extremly carefull when using om in order to avoid memory
+leaks and double free errors. Following guide lines will be very useful.</p><p>1. om_element_t struct keeps a list of attributes and a list of
+namespaces, when a namespace pointer is added to this list , it will be freed
+when this om_element is freed, Therefore same pointer to a namespace or an
+attribute should not be passed twice to a create , add or set function.</p><p>To avoid the inconvenience, clone functions have been implemented for both
+axis2_om_namespace and axis2_om_attribute structures.</p><p>2. OM returns shallow references to its string values , Therefore when
+using the returned values , AXIS2_STRDUP () function should be used</p><p>if the returned value is going to be set to another struct to avoid double
+free errors.</p><p>Example:</p><p>axis2_om_namespace_t *ns = NULL;</p><p>axis2_char_t *uri = NULL;</p><p>ns = axis2_om_namespace_create(env, "http://ws.apache.org", "om");</p><p>uri = AXIS2_OM_NAMESPACE_GET_URI(ns, env);</p><p>/** now uri points to the same place where namespace structs uri pointer
+is pointing */</p><p>Therefore following will cause a double free */</p><p>AXIS2_FREE((*env)->allocator, uri);</p><p>AXIS2_OM_NAMESPACE_FREE(ns, env);</p><p>3. when creating om programatically , if you are declaring a namespace to
+an om elment it is advisible to find whether the namespace is already
+availble in the elements scope, using find_namespace function; if available,
+that pointer can be used instead of creating another namespace struct
+instance to prevent memory leaks.</p><p><b>Complete code for the OM based document building and
+serialization</b></p><p>The following code segment shows how to use the OM for completely building
+a document and then serializing it into text pushing the output to the
+console.</p><div>
+<p><b>Code Listing 10</b></p>
+
+<p></p>
+</div>
+ <div class="source"><pre>
+#include <axis2_om_node.h>
+#include <axis2.h>
+#include <axis2_env.h>
+#include <axis2_om_element.h>
+#include <axis2_om_document.h>
+#include <axis2_om_stax_builder.h>
+#include <axis2_xml_reader.h>
+#include <axis2_log_default.h>
+#include <axis2_error_default.h>
+#include <axis2_xml_writer.h>
+#include <axis2_om_output.h>
+#include <stdio.h>
+
+
+FILE *f = NULL;
+int read_input_callback(char *buffer, int size, void* ctx)
+
+{
+ fread(buffer, (char), size, f);
+}
+int close_input_callback(void *ctx)
+{
+ fclose(f);
+}
+
+axis2_env_t * create_environment()
+
+{
+ axis2_allocator_t *allocator = NULL;
+ axis2_env_t *env = NULL;
+ axis2_log_t *log = NULL;
+
+ axis2_error_t *error = NULL;
+ allocator = axis2_allocator_init(NULL);
+ log = axis2_log_create(allocator, NULL, NULL);
+
+ error = axis2_error_create(allocator);
+ env = axis2_env_create_with_error_log(allocator, error, log);
+ env;
+}
+
+build_and_serialize_om(axis2_env_t **env)
+{
+ axis2_om_node_t *root_node = NULL;
+
+ axis2_om_element_t *root_ele = NULL;
+ axis2_om_document_t *document = NULL;
+ axis2_om_stax_builder_t *om_builder = NULL;
+
+ axis2_xml_reader_t *xml_reader = NULL;
+ axis2_xml_writer_t *xml_writer = NULL;
+ axis2_om_output_t *om_output = NULL;
+
+ axis2_char_t *buffer = NULL;
+
+ f = fopen("test.xml","r");
+ xml_reader = axis2_xml_reader_create_for_memory(env, read_input_callback,
+ close_input_callback, NULL, NULL);
+ (!xml_reader)
+ -1;
+
+ om_builder = axis2_om_stax_builder_create(env, xml_reader);
+ (!om_builder)
+ {
+ AXIS2_XML_READER_FREE(xml_reader, env);
+ AXIS2_FAILURE;
+ }
+ document = AXIS2_OM_STAX_BUILDER_GET_DOCUMENT(om_builder, env);
+ (!document)
+ {
+ AXIS2_OM_STAX_BUILDER_FREE(om_builder, env);
+ AXIS2_FAILURE;
+ }
+
+ root_node = AXIS2_OM_DOCUMENT_GET_ROOT_ELEMENT(document, env);
+ (!root_node)
+ {
+ AXIS2_OM_STAX_BUILDER_FREE(om_builder, env);
+ AXIS2_FAILURE;
+ }
+ (root_node)
+ {
+ (AXIS2_OM_NODE_GET_NODE_TYPE(root_node, env) == AXIS2_OM_ELEMENT)
+ {
+ root_ele = (axis2_om_element_t*)AXIS2_OM_NODE_GET_DATA_ELEMENT (root_node, env);
+ (root_ele)
+ {
+ printf(" %s" , AXIS2_OM_ELEMENT_GET_LOCALNAME(root_ele, env));
+ }
+ }
+ }
+ AXIS2_OM_DOCUMENT_BUILD_ALL(document, env);
+
+ xml_writer = axis2_xml_writer_create_for_memory(env, NULL, AXIS2_TRUE, 0);
+
+ om_output = axis2_om_output_create(env, xml_writer);
+
+ AXIS2_OM_NODE_SERIALIZE(root_node, env, om_output);
+ buffer = AXIS2_XML_WRITER_GET_XML(xml_writer, env);
+
+ printf("The output XML is ->>>>\n %s ", buffer);
+
+
+
+
+ AXIS2_OM_OUTPUT_FREE(om_output, env);
+
+
+ AXIS2_OM_STAX_BUILDER_FREE(om_builder, env);
+
+ AXIS2_FREE((*env)->allocator, buffer);
+
+ AXIS2_SUCCESS;
+
+}
+int main()
+{
+ int status = AXIS2_SUCCESS;
+
+ axis2_env_t *env = NULL;
+ axis2_allocator_t *allocator = NULL;
+ env = create_environment();
+
+ status = build_and_serialize_om(&env);
+
+ (status == AXIS2_FAILURE)
+ {
+ printf(" build om failed");
+ }
+
+ axis2_env_free(env);
+
+ 0;
+}
+
+
+
+</pre></div>
+ </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/userguide.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/userguide.html (added)
+++ webservices/axis2/site/c/docs/userguide.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,58 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C User's Guide</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_User_s_Guide"></a><h2>Axis2/C User's Guide</h2><p>Pages: <b>Content</b>, <a href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <a href="userguide3.html">3</a></p><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li>
+ <p><a href="userguide1.html#Introduction">Introduction</a></p>
+ <ul>
+ <li><a href="userguide1.html#Attention">Attention</a></li>
+ <li><a href="userguide1.html#What_is_Axis2_">What is Axis2/C?</a></li>
+ </ul>
+ </li>
+ <li>
+ <p><a href="userguide2.html#Web_Service_Clients_Using_Axis2">Web
+Service Clients Using Axis2/C</a></p>
+ <ul>
+ <li><a href="userguide2.html#Writing_Web_Service_Clients_using_Axis2%27s_Primary_APIs">Writing
+Web Service Clients Using Axis2's Primary APIs</a></li>
+ <ul>
+ <li><a href="userguide2.html#EchoBlockingClient">EchoBlockingClient</a></li>
+ <li><a href="userguide2.html#Request_SOAP_Message">Request SOAP
+Message</a></li>
+ <li><a href="userguide2.html#Response_SOAP_Message">Response
+SOAP Message</a></li>
+ </ul>
+ </ul>
+ </li>
+ <li>
+ <p><a href="userguide3.html#Web_Services_Using_Axis2">Web Services
+Using Axis2/C</a></p>
+ <ul>
+ <li><a href="userguide3.html#Conventions">Conventions used in the
+document</a></li>
+ <li><a href="userguide3.html#Writing_Web_Services_Using%20Axis2_C">Writing
+Web Services Using Axis2/C</a>
+ <ul>
+ <li><a href="userguide3.html#Creating_Web_Service__MyService_">Creating
+Web Service (Echo service)</a></li>
+ <li><a href="userguide3.html#How_to_write_the_Web_Service_">How
+to write the Web Service?</a>
+ <ul>
+ <li><a href="userguide3.html#Step1">Step1 :Write the
+echo_skeleton.c file implementing the axis2_svc_skeleton.h</a></li>
+ <li><a href="userguide3.html#Step2">Step2 : Now we can
+write the echo service in a file echo.c</a></li>
+ <li><a href="userguide3.html#Step3">Step3 :Write the
+services.xml file</a></li>
+ <li><a href="userguide3.html#Step4">Step4 :Create the
+WebService Folder in services folder.</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="userguide3.html#deploy">Deploy the Web Service</a></li>
+ </ul>
+ </li>
+</ul><p><a href="userguide1.html">Next Page <img src="images/arrow_right.gif" alt=""></img></a></p><p>Pages: <b>Content</b>, <a href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <a href="userguide3.html">3</a></p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/userguide1.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/c/docs/userguide1.html?rev=390460&view=auto
==============================================================================
--- webservices/axis2/site/c/docs/userguide1.html (added)
+++ webservices/axis2/site/c/docs/userguide1.html Fri Mar 31 09:02:09 2006
@@ -0,0 +1,57 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C User's Guide</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 31 March 2006
+ | Doc for 0.90</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="none"><a href="../docs/index.html">Documentation</a></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a h
ref="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_User_s_Guide"></a><h2>Axis2/C User's Guide</h2><p align="right">Pages: <a href="userguide.html">Content</a>, <b>1</b>, <a href="userguide2.html">2</a>, <a href="userguide3.html">3</a></p><p><strong>User Feedback</strong>: <a href="mailto:axis-user@ws.apache.org">axis-c-user@ws.apache.org</a> (Please
+remember to prefix the subject with [Axis2]). To subscribe to mailing list
+see <a href="../mail-lists.html">here.</a></p></div><div class="section"><a name="Introduction"></a><h2>Introduction</h2><p>Welcome to Axis2/C, the Apache Axis2 implemented in C. This User's Guide
+will help you to understand what Axis2/C has to offer and how to get started
+with it.</p><div class="subsection"><a name="What_is_Axis2_C_"></a><h3>What is Axis2/C?</h3><p>Axis2/C is an effort to implement the Axis2 architecture in C programming
+language.</p><p>After months of continued discussion and coding in this direction, Axis2/C
+now delivers the following key features:</p><ul>
+ <li><p style="margin-bottom: 0in;"><strong>Speed</strong> - Axis2/C uses
+ its own XML object model and StAX (Streaming API for XML) parsing to
+ achieve significant speed. In addition to that, Axis2/C is inherently
+ benefited by the speed of its implementation language, namely C, compared
+ to the Java implementation.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>Low memory foot print</strong>-
+ Axis2 architecture was designed ground-up keeping the low memory foot
+ print in mind. Axis2/C strives to achieve the same with a well designed
+ memory management strategy.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>AXIOM/C</strong> Axis2/C comes
+ with its own light-weight object model for XML, AXIOM/C which is the C
+ implementation of <a href="http://ws.apache.org/axis2/0_93/OMTutorial.html" class="externalLink" title="External Link">AXIOM</a>.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>MEP Support</strong> - Support
+ Message Exchange Patterns (MEP s) with in-built support for basic MEP s
+ defined in WSDL 2.0.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>Flexibility</strong> - The
+ Axis2/C architecture gives the developer complete freedom to insert
+ extensions into the engine (using modules and handlers) for custom SOAP
+ header processing.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>Transport Framework</strong> -
+ We have a clean and simple abstraction for integrating and using
+ transports and the core of the engine is completely
+ transport-independent.</p>
+ </li>
+ <li><p style="margin-bottom: 0in;"><strong>Composition and
+ Extensibility</strong> - modules and phases improve support for
+ composability and extensibility. Modules supports composability and is
+ able to add support for new WS-* specifications in a simple and clean
+ manner. They are however not hot deployable as they change the overall
+ behavior of the system.</p>
+ </li>
+</ul><p>Axis2/C team is working hard to continuously improve the implementation.
+Please note that this is an open-source effort. If you feel you have some
+time to spare, please get involved and lend us a hand! The Axis2/C developer
+community welcomes your participation and contributions.</p><p>Let us know what you think! Please send your feedback on Axis2/C to "<a href="mailto:axis-user@ws.apache.org">axis-c-user@ws.apache.org</a>" and
+please remember to prefix the subject of the mail with [Axis2].<br></br>
+<br></br>
+The following pages will guide through how to write web service clients and
+services.</p><p align="right"><a href="userguide.html"><img src="images/arrow_left.gif" alt=""></img>
+Previous</a> | <a href="userguide2.html">Next <img src="images/arrow_right.gif" alt=""></img></a></p><p>Pages: <a href="userguide.html">Content</a>, <b>1</b>, <a href="userguide2.html">2</a>, <a href="userguide3.html">3</a></p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file