You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jaxme-dev@ws.apache.org by jo...@apache.org on 2006/11/25 23:46:06 UTC
svn commit: r479221 [2/2] - in /webservices/jaxme/trunk/ws-jaxme/src: ./
site/ site/resources/ site/resources/images/ site/xdoc/ site/xdoc/api/
site/xdoc/js/ site/xdoc/js/apps/ site/xdoc/js/patterns/ site/xdoc/pm/
site/xdoc/xs/
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/placeholders.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/placeholders.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/placeholders.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/placeholders.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
+<document>
+ <header><title>Placeholders</title></header>
+ <body>
+ <section><title>Placeholders</title>
+ <p>Before describing what JaxMeJS placeholders are, we recall the use of
+ placeholders in JDBC: By preparing a statement like</p>
+ <source>
+ INSERT INTO someTable VALUES (?, ?, ?)
+ </source>
+ <p>you create the statement at one point. At some other point (typically immediately
+ after creating the statement, but not necessarily so) you add parameters to the
+ statement. For example, you tell the JDBC driver: "Replace the first question mark
+ (the first placeholder) with the string 'foo'". Likewise, you would say: "Replace
+ the second question mark with the integer 5".</p>
+ <p>A JaxMeJS placeholder is quite comparable to a JDBC placeholder. The main idea
+ is that you create one part of a method at some place and another part elsewhere.
+ The method creating the other part must know where to add code. It finds the right
+ place by using the placeholder, which the first part has set.</p>
+ </section>
+
+ <anchor id="creating"/>
+ <section><title>Creating a placeholder</title>
+ <p>A placeholder is created by invoking the method
+ <link href="../apidocs/org/apache/ws/jaxme/js/IndentationEngine.html#newPlaceHolder(String,boolean)">
+ newPlaceHolder(String,boolean)</link>. For example:</p>
+ <source>
+ JavaMethod jm;
+ PlaceHolder p = jm.newPaceHolder("MyPlaceholder", true);
+ </source>
+ <p>The method takes two arguments:</p>
+ <dl>
+ <dt>pName</dt>
+ <dd>Any placeholder has got a name. The name is the identifier by which you find the
+ placeholder. (See the <link href="#using">next section</link> for details.)</dd>
+ <dt>pAutoRemovable</dt>
+ <dd>The boolean argument indicates whether you expect to use the placeholder in
+ either case. If so, you set the "autoRemovable" argument to false. In that case,
+ you <em>must</em> remove the placeholder before serializing the method. An
+ IllegalStateException is thrown otherwise. However, if you set the "pAutoRemovable"
+ argument to true, then an existing placeholder is simply ignored while serializing
+ the method.</dd>
+ </dl>
+ </section>
+
+ <anchor id="using"/>
+ <section><title>Using the placeholder</title>
+ <p>To insert code after the placeholder, simply find it. For example:</p>
+ <source>
+ JavaMethod jm;
+ PlaceHolder p = jm.getPlaceHolder("MyPlaceholder");
+ jm.addLine("// This line follows immediately after the placeholder.");
+ </source>
+ <p>Do not forget to remove the placeholder, if the "pAutoRemovable" flag was set
+ to false while creating it:</p>
+ <source>
+ p.remove();
+ </source>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/sql.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/sql.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/sql.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/sql.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
+<document>
+ <header><title>Working with SQL</title></header>
+ <body>
+ <section><title>Working with SQL</title>
+ <warning>As of this writing, the SQL support is in early stages.
+ Some things described here are hardly more than planned and the API
+ will probably change rapidly.</warning>
+ <p>Quite many Java applications working with source generators are also
+ working with SQL. It seems natural to develop a generic SQL generation
+ framework, because it can make the actual generator much more simple and
+ readable.</p>
+ <p>The basic concepts are comparable to the Java source generation framework:
+ There is a factory, which allows you to create schema, table, column,
+ index, statement objects and the like. And there is also an API which
+ allows to manipulate these objects on a certain level of abstraction.</p>
+ <p>In what follows we describe the concept of the SQL generator by means
+ of some examples. The generator has the same objects that the actual
+ database will have: A schema, tables, columns, statements, and so on.</p>
+ </section>
+
+ <anchor id="schema"/>
+ <section><title>Creating a schema</title>
+ <p>The SQL generator assumes that any table belongs to a schema.
+ In other words, before creating a table, you have to create a schema:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.Schema;
+ import org.apache.ws.jaxme.sqls.SQLFactory;
+ import org.apache.ws.jaxme.sqls.impl.SQLFactoryImpl;
+
+ SQLFactory factory = new SQLFactoryImpl();
+ Schema schema = factory.newSchema("myschemaname");
+ System.out.println(schema.getName().toString()); // Prints myschemaname
+ </source>
+ <p>However, it is not unusual to avoid the schema. Even more, there are
+ SQL databases like <link href="ext:mysql">MySQL</link> which do not
+ even support a schema. In that case you simply use the so-called default
+ schema. The only difference between the default schema and other schemas
+ is that the former doesn't have a name.</p>
+ <source>
+ Schema schema = factory.getDefaultSchema();
+ System.out.println(schema.getName().toString()); // Prints null
+ </source>
+ </section>
+
+ <anchor id="table"/>
+ <section><title>Creating a table</title>
+ <p>Now that we have a schema, we may populate it with tables
+ and the tables with columns. Suggest the following statement:</p>
+ <source>
+ CREATE TABLE mytable (
+ id INTEGER NOT NULL PRIMARY KEY,
+ name VARCHAR(40) NOT NULL,
+ price DOUBLE,
+ UNIQUE(name));
+ </source>
+ <p>In the framework this looks like the following:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.Table;
+ import org.apache.ws.jaxme.sqls.Column;
+
+ Table mytable = schema.newTable("mytable");
+ Column id = table.newColumn("id", Column.Type.INTEGER);
+ id.setNullable(false);
+ mytable.newPrimaryKey().addColumn(id);
+ Column name = table.newColumn("name", Column.Type.VARCHAR);
+ name.setLength(40);
+ name.setNullable(false);
+ mytable.newKey().addColumn(name);
+ Column price = table.newColumn("price", Column.Type.DOUBLE);
+ </source>
+ </section>
+
+ <anchor id="insert"/>
+ <section><title>Creating an INSERT statement</title>
+ <p>Now that we have our tables, we probably want to create an
+ INSERT statement like</p>
+ <source>
+ INSERT INTO mytable (id, name, price) VALUES (?, ?, 0.0)
+ </source>
+ <p>Here's how we do this:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.InsertStatement;
+ import org.apache.ws.jaxme.sqls.SQLGenerator;
+ import org.apache.ws.jaxme.sqls.impl.SQLGeneratorImpl;
+
+ SQLGenerator generator = new SQLGeneratorImpl();
+ InsertStatement stmt = table.getInsertStatement();
+ System.out.println(generator.getQuery(stmt));
+ </source>
+ <p>The <code>getInsertStatement()</code> method is a shortcut
+ for the following:</p>
+ <source>
+ InsertStatement stmt = factory.newInsertStatement();
+ stmt.setTable(mytable);
+ stmt.addSet(id);
+ stmt.addSet(name);
+ stmt.addSet(price, (double) 0.0);
+ </source>
+ </section>
+
+ <anchor id="select"/>
+ <section><title>Creating a SELECT statement</title>
+ <p>Quite similar to the above is the creation of a SELECT statement:</p>
+ <source>
+ SELECT id, name, price FROM mytable
+ </source>
+ <p>A shortcut for the above would be:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.SelectStatement;
+
+ SelectStatement stmt = table.getSelectStatement();
+ System.out.println(generator.getQuery(stmt));
+ </source>
+ <p>The longer version goes like this:</p>
+ <source>
+ SelectStatement stmt = factory.newSelectStatement();
+ stmt.setTable(mytable);
+ stmt.addResultColumn(id);
+ stmt.addResultColumn(name);
+ stmt.addResultColumn(price);
+ </source>
+ <p>However, we possible want to add a WHERE clause like</p>
+ <source>
+ WHERE id=? AND price > 1.0
+ </source>
+ <p>This can be done like the following:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.CombinedConstraint;
+
+ CombinedConstraint whereClause = stmt.getWhere();
+ BooleanConstraint idClause = whereClause.createEQ();
+ idClause.addPart(id);
+ idClause.addPlaceHolder();
+ BooleanConstraint priceClause = whereClause.createEQ();
+ priceClause.addPart(price);
+ priceClause.addPart((double) 1.0);
+ System.out.println("SELECT statement with WHERE clause: " +
+ generator.getQuery(stmt));
+ </source>
+ </section>
+
+ <anchor id="update"/>
+ <section><title>Creating an UPDATE statement</title>
+ <p>A typical UPDATE statement for <code>mytable</code> would be</p>
+ <source>
+ UPDATE mytable SET name = 'foo', price = ? WHERE id = ?
+ </source>
+ <p>The SQL generator allows to do that in the following manner:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.UpdateStatement;
+
+ UpdateStatement stmt = schema.newUpdateStatement();
+ stmt.setTable(table);
+ stmt.addSet("name", "foo");
+ stmt.addSet("price");
+ CombinedConstraint whereClause = stmt.getWhere();
+ BooleanConstraint idClause ) whereClause.createEQ();
+ idClause.addPart(id);
+ idClause.addPlaceHolder();
+ System.out.println("UPDATE statement: " +
+ generator.getQuery(stmt));
+ </source>
+ <p>For this particular <code>UPDATE</code> query, there also
+ is a shortcut:</p>
+ <source>
+ UpdateStatement stmt = table.getUpdateStatement();
+ System.out.println("UPDATE statement: " +
+ generator.getQuery(stmt));
+ </source>
+ </section>
+
+ <anchor id="delete"/>
+ <section><title>Creating a DELETE statement</title>
+ <p>Most probably you already guess how to create the following
+ <code>DELETE</code> statement:</p>
+ <source>
+ DELETE FROM mytable WHERE id = ?
+ </source>
+ <p>The shortcut is:</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.DeleteStatement;
+
+ DeleteStatement stmt = table.getDeleteStatement();
+ System.out.println("DELETE statement: " +
+ generator.getQuery(stmt));
+ </source>
+ <p>And here is the longer version:</p>
+ <source>
+ DeleteStatement stmt = schema.newDeleteStatement();
+ stmt.setTable(table);
+ CombinedConstraint whereClause = stmt.getWhere();
+ BooleanConstraint idClause ) whereClause.createEQ();
+ idClause.addPart(id);
+ idClause.addPlaceHolder();
+ System.out.println("DELETE statement: " +
+ generator.getQuery(stmt));
+ </source>
+ </section>
+
+ <anchor id="create"/>
+ <section><title>Creating one or more CREATE TABLE statements</title>
+ <p>Is it possible to recreate the above CREATE TABLE statement from
+ the above <code>table</code> variable? Of course it is:</p>
+ <source>
+ Collection c = generator.getCreate(table);
+ for (Iterator iter = c.iterator(); iter.hasNext(); ) {
+ String s = (String) iter.next();
+ System.out.println("Statement: " + s);
+ }
+ </source>
+ <p>You probably wonder why the <code>getCreate(Table)</code> method
+ returns a collection? And you are mostly right, as the above collection
+ will typically contain a single statement. However, it is not unusual
+ that an index must be created in a separate statement. In this case
+ it might happen, that the collection returns multiple strings.</p>
+ <p>It is also possible to create a schema:</p>
+ <source>
+ Collection c = generator.getCreate(schema);
+ for (Iterator iter = c.iterator(); iter.hasNext(); ) {
+ String s = (String) iter.next();
+ System.out.println("Statement: " + s);
+ }
+ </source>
+ <p>However, you possibly want to create not only the schema, but
+ the tables as well. Voila:</p>
+ <source>
+ Collection c = generator.getCreate(schema, true);
+ for (Iterator iter = c.iterator(); iter.hasNext(); ) {
+ String s = (String) iter.next();
+ System.out.println("Statement: " + s);
+ }
+ </source>
+ </section>
+
+ <anchor id="extensions"/>
+ <section><title>Vendor specific extensions</title>
+ <p>Vendor specific extensions and vendor specific SQL dialects are available
+ through subclasses of <code>SQLFactoryImpl</code>. As of this writing, the
+ only available subclass is <code>DB2SQLFactoryImpl</code>. To use it,
+ simply replace</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.SQLFactory;
+ import org.apache.ws.jaxme.sqls.SQLFactoryImpl;
+
+ SQLFactory factory = new SQLFactoryImpl();
+ </source>
+ <p>with</p>
+ <source>
+ import org.apache.ws.jaxme.sqls.db2.DB2SQLFactory;
+ import org.apache.ws.jaxme.sqls.db2.DB2SQLFactoryImpl;
+
+ SQLFactory factory = new SQLFactoryImpl();
+ </source>
+ <p>In the special case of DB2 this will soon enable access to features like
+ table spaces or buffer pools.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/misc.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/misc.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/misc.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/misc.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties>
+ <title>Miscellaneous</title>
+ </properties>
+ <body>
+ <section name="Miscellaneous">
+ <p>This page contains miscellaneous informations for developers.</p>
+ </section>
+ <section name="Clover">
+ <p><link href="site:clover">Clover</link> is a tool that allows to trace the
+ coverage of a test suite. In short, you compile your classes using clover,
+ run the unit tests and finally receive a report which tells you, which
+ methods and lines are covered by the unit tests and, more important,
+ which aren't.</p>
+ <p>The nice thing with Clover is, that it is available at no cost for
+ open source projects like JaxMe. In other words, one can use it to
+ determine the coverage of JaxMe's test suite. Here's how to do that:</p>
+ <ol>
+ <li>To obtain a copy of Clover, you have to use the
+ <link href="site:cloverkey">JaxMe license key</link>. After accepting
+ the Clover license, you may download a ZIP file with "Clover for Ant".
+ Extract the file and copy the file lib\clover.jar to the lib folder
+ in your Ant home directory.</li>
+ <li>Choose a temporary directory. In what follows, I will assume /tmp/cloverdb.</li>
+ <li>Invoke the following Ant targets, in the same order</li>
+ </ol>
+ <source>
+ ant clean
+ ant -Dbuild.clover.db=/tmp/cloverdb all
+ ant -Dbuild.clover.db=/tmp/cloverdb test
+ ant -Dbuild.clover.db=/tmp/cloverdb test
+ ant -Dbuild.clover.db=/tmp/cloverdb clover.swing
+ </source>
+ <p>Don't ask me, why we have to call the "test" target twice. Alternatively
+ you may replace "clover.swing" with "clover.html": This will create a
+ set of HTML files with the same report.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/news.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/news.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/news.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/news.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties>
+ <title>JaxMe News</title>
+ </properties>
+ <body>
+ <section name="JaxMe News">
+ <dl>
+ <dt>2005-Aug-09: JaxMe 0.5 released</dt>
+ <dd>Compared to 0.5beta, several bugs have been fixed.</dd>
+ <dt>2005-Jul-13: JaxMe 0.5beta released</dt>
+ <dd>This release introduces support for mixed content and
+ proper inheritance of the code generated for xs:extension.</dd>
+ <dt>2005-May-19: JaxMe 0.4 released</dt>
+ <dd>Compared to the beta version, no new features have been introduced.
+ A few bugs have been fixed, mainly concerning the nested group support.</dd>
+ <dt>2005-Apr-12: JaxMe 0.4beta released</dt>
+ <dd>This release introduces support for nested groups with multiplicity <= 1.
+ In particular, xs:extension is supported now.</dd>
+ <dt>2004-Sep-03: JaxMe 0.3.1 released</dt>
+ <dd>This is a bug fix release, driven mostly by user input and feedback.
+ In particular, recursive schemas are now supported.</dd>
+ <dt>2004-Jul-25: JaxMe 0.3 released</dt>
+ <dd>The JaxMe team are proud to present the first release since
+ leaving the incubator.</dd>
+ <dt>2004-Mar-09: JaxMe has graduated to become a subproject of Apache WS</dt>
+ <dd>The <link href="ext:incubator">Apache Incubator PMC</link> has voted
+ for JaxMe to become a true subproject of the
+ <link href="ext:ws">Apache Webservices</link>.</dd>
+ <dt>2003-Nov-18: incubated-jaxme 0.2 has been released.</dt>
+ <dd>Compared to the previous release from sf.net, there haven't been
+ too many updates. This release is mainly to allow using the updated
+ package names. Besides, JaxMePM has been introduced.</dd>
+ <dt>2003-Sep-25: The JaxMe site is online</dt>
+ <dd>The new JaxMe site is online at <link href="site:jaxme">http://ws.apache.org/jaxme/</link>.</dd>
+ </dl>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/related.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/related.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/related.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/related.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties><title>Related projects</title></properties>
+ <body>
+ <section name="Related projects">
+ <p>If you are interested in JaxMe 2, you may also want to take a look
+ at the following related open source projects:</p>
+ </section>
+ <anchor id="jaxme1"/>
+ <section name="JaxMe 1">
+ <p><link href="ext:jaxme1">JaxMe 1</link> is the predecessor
+ of JaxMe 2. It has a limited support of XML structures (mainly sequences
+ and choices), but includes an integrated persistency framework that
+ allows to read the objects from or write them into the database. The
+ persistence framework includes support for JDBC mapping, XML:DB, the
+ Tamino XML database, and EJB. The framework has the additional
+ advantage of being quite mature and stable.</p>
+ </section>
+
+
+ <anchor id="jaxmexs"/>
+ <section name="JaxMeXS">
+ <p><link href="site:jaxmexs">JaxMeXS</link>, the JaxMe parser
+ for XML schema, is internally used by JaxMe 2. It is written to be
+ extensible, but not necessarily strict.</p>
+ </section>
+
+ <section name="JaxMeJS">
+ <p><link href="site:jaxmejs">JaxMeJS</link>, the
+ JaxMe Java source framework is a generic framework for writing
+ Java source generators. It used to be a part of JaxMe 1, but grew
+ up to be useful in itself and finally was moved to a separate
+ distribution. JaxMe 2 is still based on the latest version, which
+ also includes an SQL generator.</p>
+ </section>
+
+ <section name="eXist">
+ <p><link href="site:exist">eXist</link> is a native XML database
+ engine written in Java. It can be used standalone (via a dedicated
+ TCP port), as part of a servlet engine (accessible via HTTP),
+ or embedded into a Java application. This last approach is
+ particularly useful for JUnit testing. JaxMe 1 uses eXist for
+ testing its xml:db API.</p>
+ </section>
+
+ <section name="hsqldb">
+ <p><link href="site:hsqldb">hsqldb</link> is an SQL database
+ and also written in Java. Like eXist, it can be used in embedded
+ mode and it is also used by JaxMe 1, JaxMe 2, and JaxMeJS for JUnit
+ tests.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/resources.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/resources.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/resources.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/resources.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties>
+ <title>Resources</title>
+ </properties>
+ <body>
+ <anchor id="jira"/>
+ <section name="Bug tracking system">
+ <p>To file a bug report or search for known bugs, use
+ <link href="ext:jira">Jira</link>.</p>
+ </section>
+
+ <anchor id="view-svn"/>
+ <section name="Browse the JaxMe sources">
+ <p>
+Thanks to Subversion, the contents of the JaxMe SVN project
+can be <link href='ext:jaxmerepo'>browsed online</link>.
+ </p>
+ </section>
+
+ <anchor id="jelly-jaxme"/>
+ <section name="JaxMe Jelly Tag Library">
+ <p>
+<link href='ext:jelly'>Jelly</link> is a tool for turning XML into executable code.
+One common use is to drive complex build scripts typically embedding ant but Jelly's
+flexibility is it's strength. There are many uses to which Jelly can be put.
+ </p>
+ <p>
+Jelly is extensible. The principle way that Jelly can be extended is through jelly
+tag libraries. If you know JSP custom tags, then this idea should be pretty familiar.
+ </p>
+ <p>
+(Basic) Jelly tag libraries for JaxMe can be found
+<link href='ext:jaxme-jelly-tag-library'>here</link> and a list of tags
+<link href='ext:jaxme-jelly-tags'>here</link>.
+ </p>
+ </section>
+
+ <anchor id="Wiki"/>
+ <section name="The JaxMe Wiki">
+ <p>The <link href="ext:wiki">JaxMe Wiki</link> allows
+ you to add notes, opinions, suggestions, or whatever
+ else may make sense for others to know. And, of course,
+ you may also view other peoples notes, opinions, etc.
+ there. :-)</p>
+ </section>
+
+ <anchor id="FAQ"/>
+ <section name="The JaxMe FAQ">
+ <p>A <link href="ext:faq">JaxMe FAQ</link> is available
+ as part of the <link href="ext:wiki">JaxMe Wiki</link>.
+ Note, that you are able to add questions or modify answers
+ in the Wiki.</p>
+ </section>
+
+ <anchor id="External"/>
+ <section name="External links">
+ <p><link href="mailto:brett@oreilly.com">Brett McLaughlin</link>,
+ author of <link href="http://www.oreilly.com/catalog/javaxml2/index.html">
+ Java & XML</link>, and
+ <link href="http://www.oreilly.com/catalog/javaxmldatabind/index.html">
+ Java & XML Data Binding</link>, and
+ <link href='ext:zeus'>Zeus</link>, wrote a very nice article on JaxMe:
+ <link href="http://www-106.ibm.com/developerworks/xml/library/x-pracdb4/">
+ Practical data binding: JaxMe - The new kid on the block</link>.
+ The second part is
+ <link href="http://www-106.ibm.com/developerworks/library-combined/x-pracdb5.html">
+ Practical data binding: Converting to and from XML with JaxMe</link>.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/generic.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/generic.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/generic.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/generic.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties>
+ <title>The generic parser</title>
+ </properties>
+ <body>
+ <section name="The generic parser">
+ <p>The most basic part of JaxMeXS is its generic parser. This part is suited
+ for arbitrary XML document types, for example configuration files and the
+ like. The actual XML Schema parsers (the
+ <a href="syntax.html">syntax parser</a> and the
+ <a href="logical.html">logical parser</a>) are sitting on top of
+ the generic parser. If you aren't interested in the generic part, you may
+ safely skip to the <a href="syntax.html">next section</a>, which is basically
+ self contained. However, some details are best described here.</p>
+ <p>The generic parser follows an idea from the
+ <a hrefkey="link.ant">Ant</a> project: A SAX parser is responsible for the
+ configuration of a bean. Any XML element is mapped to a Java bean. The XML
+ elements attributes are mapped to properties of the bean and the child
+ elements are mapped to other beans, which are part of the parent bean. If
+ you know <a hrefkey="link.antwritingowntask">how to write an Ant task</a>,
+ you know how the generic parser works.</p>
+ <p>The generic parser is specified by the interface
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/XsSAXParser.html">XsSAXParser</a> and
+ implemented by the class
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/impl/XsSAXParserImpl.html">XsSAXParserImpl</a>.
+ There's few things to know about that. The most important parts are some other
+ interfaces and classes which you might like to implement or extend:</p>
+ <ol>
+ <li>The <a href="#AttributeSetter">AttributeSetter</a>
+ interface is responsible for mapping XML attributes to bean properties.</li>
+ <li>The <a href="#TextSetter">TextSetter</a> handles character data contained
+ in elements.</li>
+ <li>And, finally, the <a href="#ChildSetter">ChildSetter</a> creates new beans
+ for any child element.</li>
+ </ol>
+ </section>
+
+ <anchor id="AttributeSetter"/>
+ <section name="The AttributeSetter interface">
+ <p>The <a href="./apidocs/org/apache/ws/jaxme/xs/parser/AttributeSetter.html">AttributeSetter</a>
+ interface consists of a single method:</p>
+ <source>
+ public void setAttribute(String pQName, String pNamespaceURI,
+ String pLocalName, String pValue) throws SAXException;
+ </source>
+ <p>This method is invoked for any attribute that the SAX parser finds.</p>
+ <p>The AttributeSetters main idea is as follows: Suggest, that the attributes local
+ name is <code>foo</code>. A method <code>setFoo(SomeClass pValue)</code> is searched.
+ f such a method is found, the attribute value is converted into an instance of
+ <code>SomeClass</code> and the method is invoked. More formally, the default
+ implementation <a href="./apidocs/org/apache/ws/jaxme/xs/parser/impl/AttributeSetterImpl.html">
+ AttributeSetterImpl</a> behaves as follows:</p>
+ <ol>
+ <li>If the bean has a method <code>setAttribute(String, String, String, String)</code>,
+ it is invoked with the same arguments <code>pQName</code>, <code>pNamespaceURI</code>,
+ <code>pLocalName</code>, <code>pValue</code>. If this method does not have
+ the result types <code>boolean</code> or <code>Boolean</code>, or if the result
+ is <code>true</code>, then the <code>AttributeSetterImpl</code> assumes that the
+ property is set.</li>
+ <li>If the property is not set, and the bean has a method
+ <code>setProperty(String)</code>, then this method is invoked
+ with the attribute value.</li>
+ <li>Otherwise, if the bean has a method <code>setProperty(T)</code>, and
+ the class <code>T</code> has either of a method
+ <code>public static T valueOf(String)</code> or a constructor
+ <code>public T(String)</code> (in that order), then the method
+ <code>setProperty(T)</code> is invoked with the value obtained
+ by an invocation of the method <code>valueOf()</code>, or
+ the constructor, respectively. Note, that this applies in
+ particular to the classes Long, Integer, Short, Byte, Double,
+ Float, java.math.BigInteger, java.math.BigDecimal,
+ java.io.File, and StringBuffer.</li>
+ <li>If the bean has a method <code>setProperty(boolean)</code>,
+ the method will be invoked with the value <code>true</code>
+ (the value specified in the XML file is either of
+ <code>true</code>, or <code>1</code>) or <code>false</code>
+ (the attribute has any other value).</li>
+ <li>If the bean has a method <code>setProperty(char)</code>,
+ or <code>setProperty(Character)</code>, the method will be
+ invoked with the first character of the value specified in
+ the XML file. If the value contains zero or multiple characters,
+ an IllegalArgumentException is thrown.</li>
+ <li>If the bean has either of the following methods, in that order:
+ <ul>
+ <li><code>setProperty(long)</code></li>
+ <li><code>setProperty(int)</code></li>
+ <li><code>setProperty(short)</code></li>
+ <li><code>setProperty(byte)</code></li>
+ <li><code>setProperty(double)</code></li>
+ <li><code>setProperty(float)</code></li>
+ </ul>
+ then the attribute value is converted into the respective type
+ and the method is invoked. An IllegalArgumentException
+ is thrown, if the conversion fails.</li>
+ <li>If the bean has a method <code>java.lang.Class</code>, the
+ <code>XsSAXParser</code> will interpret the value given in the
+ XML file as a Java class name and load the named class from its
+ class loader. If the class cannot be loaded, it will also try
+ to use the current threads context class loader. An
+ exception is thrown, if neither of the class loaders can
+ load the class.</li>
+ </ol>
+ </section>
+
+ <anchor id="TextSetter"/>
+ <section name="The TextSetter interface">
+ <p>The <a href="./apidocs/org/apache/ws/jaxme/xs/parser/TextSetter.html">TextSetter</a>
+ interface is invoked from within the SAX ContentHandlers method
+ <code>characters(char[] pBuffer, int pOffset, int pLen)</code>.
+ It's task is to fill the bean with character data. Note, that the latter
+ method may very well be called multiple times, even for a single
+ character sequence in the XML file. For example, if the XML reader
+ loads the XML file in blocks of 1024 characters and a block stops
+ right within an elements character data, then it is valid behaviour
+ to call the <code>character(char[], int, int)</code> method twice:
+ Once for the first part, which sits at the end of the 1024 characters
+ and once for the remaining part. The same holds for the <code>addText()</code>
+ method:</p>
+ <source>
+ public void addText(String pValue) throws SAXException;
+ </source>
+ <p>The default implementation is
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/impl/TextSetterImpl.html">
+ TextSetterImpl</a>, which behaves as follows:</p>
+ <ol>
+ <li>If the bean has a method with the same signature
+ <code>public void addText(String)</code>, then the method is invoked.</li>
+ <li>If the bean doesn't have such a method and the supplied text is
+ all whitespace, then the text is ignored. Otherwise an exception
+ is thrown.</li>
+ </ol>
+ </section>
+
+ <anchor id="ChildSetter"/>
+ <section name="Handling child elements">
+ <p>Embedded child elements are handled by the interface
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/ChildSetter.html">ChildSetter</a> and
+ its default implementation
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/impl/ChildSetterImpl.html">ChildSetterImpl</a>.
+ The interface exposes a single method:</p>
+ <source>
+ public ContentHandler getChildHandler(String pQName, String pNamespaceURI,
+ String pLocalName) throws SAXException;
+ </source>
+ <p>The purpose of the method is to create a SAX handler for this element.
+ If such a handler is returned, then it receives the SAX events generated
+ for the element. The default implementation works as follows:</p>
+ <ol>
+ <li>If the bean has a method with the same signature
+ <code>public ContentHandler getChildHandler(String, String, String, String)</code>,
+ then this method is invoked. A non-null result will be used as a ContentHandler
+ for the child element.</li>
+ <li>If the bean doesn't have such a method or if the method returned null,
+ and the local name is <code>foo</code>, then a method
+ <code>public T createFoo()</code> is searched, with an arbitrary result type T.
+ If there is such a method it is invoked and a new instance of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/parser/impl/XsSAXParserImpl.html">XsSAXParserImpl</a>
+ is created to configure the bean.</li>
+ <li>An exception is thrown otherwise.</li>
+ </ol>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/index.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/index.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/index.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/index.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<document>
+ <properties>
+ <title>
+ The JaxMe parser for XML Schema
+ </title>
+ </properties>
+ <body>
+ <section name="The JaxMe parser for XML Schema">
+ <p>This is JaxMeXS, a parser for XML schema. Yet another one, to be precise. As there
+ are a lot of other parsers around, the question arises: What makes it different?
+ What advantages does it have?</p>
+ <p>Let's begin with a disadvantage: This one is not a strict parser. In other words,
+ it was not written to detect any possible invalid schema. Strictness is a secondary
+ goal.</p>
+
+ <p>The main purpose of JaxMeXS is being extensible. It is written with XML languages
+ in mind, that extend XML schema. The best example is <a hrefkey="link.jaxb">JAXB</a>,
+ the XML binding specification for Java. It extends XML schema by adding some more tags,
+ for example like this:</p>
+ <source>
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ targetNamespace="http://ws.apache.org/jaxme/examples/misc/jaxb"
+ xmlns:jaxb="http://java.sun.com/xml/ns/jaxb">
+ <xs:annotation>
+ <xs:appinfo>
+ <jaxb:schemaBindings>
+ <jaxb:package name="com.mycompany.xml"/>
+ </jaxb:schemaBindings>
+ </xs:appinfo>
+ </xs:annotation>
+ ...
+ </source>
+ <p>JAXB is a Java source generator, which converts an XML schema into Java classes.
+ These Java classes have the ability to read an XML document conforming to the
+ original schema and return its information. As usual for Java classes, they
+ have to be located in some package, <code>com.mycompany.xml</code> in our case.
+ The above example demonstrates how JAXB uses an additional tag
+ <code>jaxb:package</code> to specify it.</p>
+ <p>This is exactly where JaxMeXS fits in. Quite unsurprising, because it was
+ written as the XML schema parser for <a hrefkey="link.jaxme2">JaxMe</a>,
+ which aims to be a JAXB implementation and extends the JAXB language by even
+ more tags. The main idea of JaxMeXS is:</p>
+ <ul>
+ <li>Write a parser for XML schema.</li>
+ <li>Extend the parser with the JAXB tags. This is simple: Any additional
+ element is implemented by a standard Java bean. The attributes are
+ mapped to properties and the property setters are called almost automagically.</li>
+ <li>Extend the JAXB parser with the JaxMe tags by adding more beans.</li>
+ </ul>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/logical.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/logical.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/logical.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/logical.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+ <properties><title>The logical parser</title></properties>
+ <body>
+ <section name="The logical parser">
+ <p>As we have <a href="syntax.html">already said</a>, the JaxMe
+ parser for XML Schema, is an application of multiple layers. There is a
+ <a href="generic.html">generic parser</a>,
+ which is mostly independent of a certain XML language. The second layer
+ is the <a href="syntax.html">syntax parser</a>, which you typically
+ do not want to use. Most probably you are mainly interested in the topmost
+ layer: The logical parser.</p>
+ <p>The logical parser presents the XML Schema in a way, which you will
+ definitely like, because it is easy to use and frees you from the burden
+ to understand XML Schema. It handles groups, restrictions, extensions,
+ redefinitions and all that kind of stuff for you. Ideally you do not even
+ notice, that they are in use.</p>
+ <ul>
+ <li><a href="#use">Using</a> the logical parser</li>
+ <li>Accessing locical <a href="#context">context information</a></li>
+ </ul>
+ </section>
+
+ <anchor id="use"/>
+ <section name="Using the logical parser">
+ <p>The logical parser is used as follows:</p>
+ <source><![CDATA[
+ import java.io.File;
+ import java.io.FileInputStream;
+ import org.apache.ws.jaxme.xs.XSElement;
+ import org.apache.ws.jaxme.xs.XSParser;
+ import org.apache.ws.jaxme.xs.XSSchema;
+ import org.xml.sax.InputSource;
+
+ XSParser xsp = new XSParser();
+ // xsp.setValidating(false); // In case your schema does not contain a schema declaration
+ File f = new File("myschema.xsd");
+ InputSource isource = new InputSource(new FileInputStream(f));
+ isource.setSystemId(f.toURL().toString());
+ XSSchema schema = xsp.parse(isource);
+
+ // Print the names of all global elements:
+ XSElement[] elements = schema.getElements();
+ for (int i = 0; i < elements.length; i++) {
+ System.out.println(elements[i].getName());
+ }
+]]> </source>
+ </section>
+
+ <anchor id="context"/>
+ <section name="Accessing logical context information">
+ <p>Within your own beans or bean methods, it might be interesting from
+ time to time, whether you are currently within an imported or included
+ schema. If so, you might also want to know about the outer schemas.
+ Access to these items is provided through</p>
+ <source>
+ getXSSchema().getContext().getXSLogicalParser().getSyntaxSchemas()
+ </source>
+ </section>
+ </body>
+</document>
+
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/syntax.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/syntax.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/syntax.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/syntax.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,300 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ Copyright 2004 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+ <properties><title>The syntax parser</title></properties>
+ <body>
+ <section name="The syntax parser">
+ <p>JaxMeXS mainly consists of three parts: A
+ <a href="generic.html">generic parser</a>, which is by no means
+ restricted to XML schema, a syntax parser, which is is dedicated to the
+ syntactical aspects of XML schema, and a structure parser, which understands
+ the logic. Extending JaxMeXS will always imply extending the syntax parser. In the
+ most cases this will even be sufficient: Who's interested in creating a language as
+ complex as XML schema?</p>
+ <p>The syntax parser is an application of the
+ <a href="generic.html">generic parser</a>. This means, that it converts
+ any element in the XML schema into a Java bean. The attributes and elements are
+ mapped to bean properties. Attributes have simple values like strings or integers,
+ but a child element is yet another bean. In what follows, we'll discuss the following
+ aspects:</p>
+ <ol>
+ <li><a href="#using">Using</a> the syntax parser.</li>
+ <li>Making the schema parser to use <a href="#XsObjectFactory">your own beans</a>.</li>
+ <li>Adding new <a href="#attributes">attributes</a> to an existing schema element.</li>
+ <li>Handling <a href="#namespaces">different namespaces</a>.</li>
+ <li>Adding new <a href="#childElements">child elements</a>.</li>
+ </ol>
+ </section>
+
+ <anchor id="using"/>
+ <section name="Using the syntax parser">
+ <p>To use the syntax parser, instantiate the class
+ <a href="./apidocs/org/apache/ws/jaxme/xs/XSParser.html">XSParser</a> and invoke
+ its <code>parse()</code> method, for example like this:</p>
+ <source>
+ import java.io.FileInputStream;
+ import org.xml.sax.InputSource;
+ import org.apache.ws.jaxme.xs.XSParser:
+
+ public class MyParser {
+ public static void main(String[] args) throws Exception {
+ FileInputStream fs = new FileInputStream(args[0]);
+ InputSource is = new InputSource(fs);
+ is.setSystemId(fs.toURL().toString()); // This is important, if you use a DTD,
+ // external entities, schema validation, ...
+ // in other words: Other files
+ XSParser parser = new XSParser();
+ XsESchema schema = parser.parseSyntax(is);
+ }
+ }
+ </source>
+ <p>That's it! The returned instance of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/XsESchema.html">XsESchema</a> is a
+ standard schema with methods like <code>getTargetNamespace()</code> or
+ <code>getChilds()</code>. For example, the list of global types can be retrieved
+ as follows:</p>
+ <source><![CDATA[
+ Object[] childs = schema.getChilds();
+ for (int i = 0; i < childs.length; i++) {
+ Object o = childs[i];
+ if (o instanceof XsETopLevelSimpleType) {
+ XsETopLevelSimpleType t = (XsETopLevelSimpleType) o;
+ System.out.println("Simple type: " + t.getName());
+ } else if (o instanceof XsTComplexType) {
+ XsTComplexType t = (XsTComplexType) o;
+ System.out.println("Complex type: " + t.getName());
+ }
+ }
+]]> </source>
+ <p>This is not very comfortable, but the intent of the syntax parser is simplicity,
+ and not comfort.</p>
+ </section>
+
+ <anchor id="XsObjectFactory"/>
+ <section name="Forcing the schema parser to use your own beans">
+ <p>The beans returned by the schema parser are instances of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/impl/XsObjectImpl.html">XsObjectImpl</a>,
+ implementing the interface
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/XsObject.html">XsObject</a>.
+ The <code>XsObject</code> interface allows access to the SAX location.</p>
+ <p>However, you might replace these completely with own implementations:
+ The <a href="./apidocs/org/apache/ws/jaxme/xs/xml/XsObjectFactory.html">object factory</a>
+ makes it possible.</p>
+ <p>Any of the standard XML schema beans is created by the object factory.
+ For example, the method <code>newXSESchema()</code> is invoked to create
+ the schema bean. We take this bean as an example and change the behaviour
+ of its attribute <code>targetNamespace</code>. For compatibility reasons
+ we want to replace the namespace <code>http://company.com/namespaces/version1</code>
+ with <code>http://company.com/namespaces/version2</code>. To achieve that,
+ we have to create three classes:</p>
+ <ol>
+ <li>A subclass of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/impl/XsESchemaImpl.html">XsESchemaImpl</a>
+ with a modified <code>setTargetNamespace()</code> method,</li>
+ <li>an updated object factory, that doesn't create an instance of the base class,
+ but an instance of our subclass,</li>
+ <li>and, finally, a parser that uses our own object factory.</li>
+ </ol>
+ <p>Let's begin with the first task:</p>
+ <source>
+ import org.xml.sax.Locator;
+ import org.apache.ws.jaxme.xs.xml.XsObjectFactory;
+ import org.apache.ws.jaxme.xs.xml.impl.XsESchemaImpl;
+
+ public class MySchema extends XsESchemaImpl {
+ protected MySchema(XsObjectFactory pFactory, Locator pLocator) {
+ super(pFactory, pLocator);
+ }
+ public void setTargetNamespace(XsAnyURI pURI) {
+ if (pURI.equals("http://company.com/namespaces/version1")) {
+ pURI = "http://company.com/namespaces/version2";
+ }
+ super.setTargetNamespace(pURI);
+ }
+ }
+ </source>
+ <p>Neat, isn't it? Now, here's the object factory:</p>
+ <source>
+ import org.apache.ws.jaxme.xs.xml.XsESchema;
+ import org.apache.ws.jaxme.xs.xml.impl.XsObjectFactoryImpl;
+
+ public class MyXsObjectFactory extends XsObjectFactoryImpl {
+ public XsESchema newXsESchema() {
+ return new MySchema(this, getLocator());
+ }
+ }
+ </source>
+ <p>You probably already guess how the parser looks like:</p>
+ <source>
+ import org.apache.ws.jaxme.xs.XSParser;
+
+ public class MyParser extends XSParser {
+ public MyParser() {
+ getData().setXsObjectFactory(new MyXsObjectFactory());
+ }
+ }
+ </source>
+ <p>Now we have a parser, which does no longer distinguish between
+ <code>http://company.com/namespaces/version2</code> and
+ <code>http://company.com/namespaces/version1</code> in the
+ target namespace.</p>
+ </section>
+
+ <anchor id="attributes"/>
+ <section name="Adding new attributes to an existing schema element">
+ <p>We already know how to extend the parser.This knowledge will be
+ applied in the following example: We'll have an an additional
+ attribute "ignore" in the element definition. It ought to have a
+ boolean value. (For example, the attribute might indicate that
+ a custom program should ignore the element.)</p>
+ <p>The attribute is introduced by adding a property "ignore" to
+ the "element" bean. This might look like this:</p>
+ <source>
+ import org.xml.sax.Locator;
+ import org.apache.ws.jaxme.xs.xml.XsObjectFactory;
+ import org.apache.ws.jaxme.xs.xml.impl.XsTElementImpl;
+
+ public class MyElement extends XsTElementImpl {
+ private boolean ignoreMe;
+
+ protected MyElement(XsObjectFactory pFactory, Locator pLocator) {
+ super(pFactory, pLocator);
+ }
+ public void setIgnore(boolean pIgnore) {
+ ignoreMe = pIgnore;
+ }
+ public boolean getIgnore() {
+ return ignoreMe;
+ }
+ }
+ </source>
+ <p>We are not yet done. As we are using an own bean, we have to extend
+ the object factory to return this bean, if the method
+ <code>newXsTElementImpl()</code> is invoked. We also have to extend
+ the parser to use the extended object factory. These steps have already
+ been described in the <a href="#XsObjectFactory">previous section</a>,
+ so we omit it here.</p>
+ </section>
+
+ <anchor id="namespaces"/>
+ <section name="Handling different namespaces">
+ <p>What we did in the <a href="#attributes">previous</a> section on
+ <a href="#attributes">adding attributes</a>, wasn't really conforming
+ to XML Schema. Our attribute had the default namespace, as the standard
+ XML Schema attributes do. Any other namespace had been a better choice.
+ XML Schema allows to include arbitrary attributes into a schema, as long
+ as they do not have the XML schema namespace. Surprisingly, the default
+ namespace isn't implicitly forbidden. Anyways, such behaviour cannot be
+ recommended.</p>
+ <p>To support attributes from other namespaces, we'll have to add another
+ method to our bean. The method is called</p>
+ <source>
+ public boolean setAttribute(String pQName, String pNamespaceURI,
+ String pLocalName, String pValue)
+ throws SAXException;
+ </source>
+ <p>The boolean return value allows the method a decision to handle an
+ attribute (for example, if it is defined in a particular additional
+ namespace) by returning <code>true</code> or to leave the attribute
+ to the standard mechanisms by returning <code>false</code>. A typical
+ implementation might look like this:</p>
+ <source>
+ if (!"http://company.com/namespaces/mynamespace".equals(pNamespaceURI)) {
+ return false;
+ }
+ if ("ignore".equals(pLocalName)) {
+ setIgnore(Boolean.valueOf(pValue).booleanValue());
+ } else {
+ throw new SaxParseException("Invalid attribute: " + pValue, getLocation());
+ }
+ </source>
+ <p>The meaning is obvious: We feel responsible for the namespace
+ <code>http://company.com/namespaces/mynamespace</code>. If the attributes
+ namespace is different, we simply return false. If the namespace matches,
+ we accept the attribute "ignore", and refuse all others by throwing a
+ <code>SAXException</code>.</p>
+ </section>
+
+ <anchor id="childElements"/>
+ <section name="Adding new child elements">
+ <p>The handling of a new child is no more complex than the handling of
+ attributes. In fact, it works quite the same. Basically one creates a
+ new bean and adds a bean property to the parent element, as in the following
+ example:</p>
+ <source>
+ MyChildBean childBean;
+
+ public MyChildBean createMyChild() {
+ if (childBean != null) {
+ throw new IllegalStateException("Multiple 'myChild' elements are forbidden.");
+ }
+ childBean = new MyChildBean();
+ }
+
+ public MyChildBean getMyChild() {
+ return childBean;
+ }
+ </source>
+ <p>This code is added to the parent bean. For example, if we want to have a new
+ element <code>xs:schema/xs:myChild</code>, we could create a new subclass of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/impl/XsESchemaImpl.html">XsESchemaImpl</a>
+ with the above code. By extending the object factory to use our updated schema
+ bean and extending the parser to use our private object factory, we would be
+ done. (The latter steps are as in the first example section on
+ <a href="#XsObjectFactory">using our own beans</a>.)</p>
+ <p>There are two possible reasons, why the above code might be insufficient:
+ First of all, the example obviously doesn't care for namespaces. Second,
+ there's a chance that we do not want to create a simple bean. For example,
+ the standard behaviour of
+ <a href="./apidocs/org/apache/ws/jaxme/xs/xml/impl/XsEAppinfoImpl.html">XsEAppinfo</a>
+ is to convert child elements into DOM documents.</p>
+ <p>Both becomes possible by the following example:</p>
+ <source>
+ import org.xml.sax.ContentHandler;
+ import org.apache.ws.jaxme.xs.parser.impl.XsSAXParserImpl;
+
+ MyChildBean childBean;
+
+ public ContentHandler getChildHandler(String pQName, String pNamespaceURI,
+ String pLocalName) throws SAXException {
+ if (!"http://company.com/namespaces/mynamespace".equals(pNamespaceURI)) {
+ return null;
+ }
+ if ("myChild".equals(pLocalName)) {
+ if (childBean != null) {
+ throw new IllegalStateException("Multiple 'myChild' child elements are forbidden.");
+ }
+ childBean = new MyChildBean();
+ return new XsSAXParserImpl(childBean);
+ } else {
+ throw new IllegalStateException("Unknown child element: " + pQName);
+ }
+ }
+
+ public MyChildBean getMyChild() {
+ return childBean;
+ }
+ </source>
+ <p>Besides the different namespace, the example is functionally equivalent to
+ the previous example.</p>
+ </section>
+ </body>
+</document>
+
---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org