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 [1/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/
Author: jochen
Date: Sat Nov 25 14:46:04 2006
New Revision: 479221
URL: http://svn.apache.org/viewvc?view=rev&rev=479221
Log: (empty)
Added:
webservices/jaxme/trunk/ws-jaxme/src/
webservices/jaxme/trunk/ws-jaxme/src/site/
webservices/jaxme/trunk/ws-jaxme/src/site/resources/
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/group-logo.gif (with props)
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/icon.png (with props)
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-application-workflow.png (with props)
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-compiler-workflow.png (with props)
webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/spacer.gif (with props)
webservices/jaxme/trunk/ws-jaxme/src/site/site.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/index.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/index.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/book.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/xmlrpc.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/book.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/factory.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/index.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/jparser.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/methods.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/optimizations.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/book.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/chains.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/proxy.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/typesafeenum.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/versioning.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/placeholders.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/sql.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/misc.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/news.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/pm/
- copied from r479015, webservices/jaxme/trunk/ws-jaxme/projects/pm/xdocs/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/related.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/resources.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/generic.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/index.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/logical.xml
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/xs/syntax.xml
Removed:
webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/pm/navigation.xml
Added: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/group-logo.gif
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/group-logo.gif?view=auto&rev=479221
==============================================================================
Binary file - no diff available.
Propchange: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/group-logo.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/icon.png
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/icon.png?view=auto&rev=479221
==============================================================================
Binary file - no diff available.
Propchange: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/icon.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-application-workflow.png
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-application-workflow.png?view=auto&rev=479221
==============================================================================
Binary file - no diff available.
Propchange: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-application-workflow.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-compiler-workflow.png
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-compiler-workflow.png?view=auto&rev=479221
==============================================================================
Binary file - no diff available.
Propchange: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/jaxme-compiler-workflow.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/spacer.gif
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/spacer.gif?view=auto&rev=479221
==============================================================================
Binary file - no diff available.
Propchange: webservices/jaxme/trunk/ws-jaxme/src/site/resources/images/spacer.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/jaxme/trunk/ws-jaxme/src/site/site.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/site.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/site.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/site.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,73 @@
+<project name="ws-site">
+ <bannerLeft>
+ <name>Apache JaxMe</name>
+ <src>http://ws.apache.org/jaxme/images/group-logo.gif</src>
+ <href>http://ws.apache.org/jaxme/</href>
+ </bannerLeft>
+ <body>
+ <links>
+ <item name="Apache" href="http://www.apache.org/"/>
+ <item name="Webservices" href="http://ws.apache.org/"/>
+ <item name="JaxMe" href="http://ws.apache.org/jaxme/"/>
+ </links>
+
+ <menu name="JaxMe 2">
+ <item name="About" href="index.html"/>
+ <item name="News" href="news.html"/>
+ <item name="Downloads" href="downloads.html"/>
+ <item name="Mailing Lists" href="mail-lists.html"/>
+ <item name="License" href="license.html"/>
+ <item name="Resources" href="resources.html"/>
+ <item name="Related Projects" href="related.html"/>
+ <item name="Documentation" collapse="true">
+ <item name="Manual" href="manual/index.html"/>
+ <item name="Javadocs" href="apidocs/index.html"/>
+ </item>
+ <item name="Developer Resources" collapse="true">
+ <item name="How to create a release" href="release.html"/>
+ <item name="Missing features" href="features.html"/>
+ <item name="Miscellaneous" href="misc.html"/>
+ </item>
+ </menu>
+
+ <menu name="JAXB API">
+ <item name="Introduction" href="api/index.html"/>
+ </menu>
+
+ <menu name="JaxMe JS">
+ <item name="Introduction" href="js/index.html"/>
+ <item name="The JavaSource factory" href="js/factory.html"/>
+ <item name="Writing methods" href="js/methods.html"/>
+ <item name="Placeholders" href="js/placeholders.html"/>
+ <item name="Optimizations" href="js/optimizations.html"/>
+ <item name="Writing SQL" href="js/sql.html"/>
+ <item name="Java Source Reflection" href="js/jparser.html"/>
+ <item name="Patterns" collapse="true">
+ <item name="Proxy Objects" href="js/patterns/proxy.html"/>
+ <item name="Multiple Inheritance" href="js/patterns/proxy.html#multiple_inheritance"/>
+ <item name="Typesafe Enumerations" href="js/patterns/typesafeenum.html"/>
+ <item name="Proxy chains" href="js/patterns/chains.html"/>
+ <item name="Versioning" href="js/patterns/versioning.html"/>
+ </item>
+ <item name="Applications" collapse="true">
+ <item name="Apache XML-RPC Clients" href="js/apps/xmlrpc.html"/>
+ </item>
+ </menu>
+
+ <menu name="JaxMe XS">
+ <item name="Introduction" href="xs/index.html"/>
+ <item name="Generic XML Parser" href="xs/generic.html"/>
+ <item name="Syntax Parser" href="xs/syntax.html"/>
+ <item name="Logical Parser" href="xs/logical.html"/>
+ </menu>
+
+ <menu name="JaxMe PM">
+ <item name="Introduction" href="pm/index.html"/>
+ <item name="JDBC" href="pm/jdbc.html"/>
+ <item name="Tamino" href="pm/ino.html"/>
+ </menu>
+
+ ${reports}
+
+ </body>
+</project>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/index.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/index.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/index.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/api/index.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,78 @@
+<?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>
+ JaxMeAPI: A clean room implementation of the JAXB API
+ </title>
+ </properties>
+ <body>
+ <section
+ name="JaxMeAPI: A clean room implementation of the JAXB API">
+ <p>
+ JaxMeAPI is clean room implementation of the JAXB API.
+ Unlike the
+ <a hrefkey="link.ext-ri">reference implementation</a>
+ this one comes under a very moderate open source
+ license, the
+ <a hrefkey="link.apache-license">Apache License</a>.
+ </p>
+ <table border="1">
+ <tr>
+ <th>Note</th>
+ </tr>
+ <tr>
+ <td>
+ The reference implementation is now distributed
+ from
+ <a hrefkey='link.jaxb-si'>Java Dot Net</a>.
+ Though the source may be viewed, the license
+ model used does not really seem to be open
+ source (in the usual sense of
+ <a hrefkey='link.open-source-definition'>
+ The Open Source Initiative
+ </a>
+ definition). Our implementation (of the basic
+ API) is licensed under the Apache License a
+ truly open source license allowing easy
+ redistribution. Therefore, we continue to
+ recommend our implementation.
+ </td>
+ </tr>
+ </table>
+ <p>
+ In terms of Jar files, the JaxMeAPI is equivalent to the
+ following Jar files from the reference implementation:
+ </p>
+ <ol>
+ <li>jaxb-api.jar</li>
+ <li>jax-qname.jar</li>
+ <li>namespace.jar</li>
+ </ol>
+ <p>
+ JaxMeAPI was written as a part of the
+ <a hrefkey="link.jaxme2">JaxMe 2</a>
+ project. It is available as a separate module to be
+ included in source distributions of JAXB client
+ applications. Perhaps other JAXB provider
+ implementations. might be interested too at some point.
+ </p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/index.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/index.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/index.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,65 @@
+<?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>Welcome to JaxMe 2</title>
+ </properties>
+ <body>
+ <section name="Welcome to JaxMe 2">
+ <p>
+ JaxMe 2 is an open source implementation of
+ <link href="site:jaxb"><code>JAXB</code></link>, the specification for
+ Java/XML binding.
+ </p>
+ <p>A Java/XML binding compiler takes as input a schema
+ description (in most cases an XML schema but it may be a DTD, a
+ RelaxNG schema, a Java class inspected via reflection or a database
+ schema). The output is a set of Java classes:
+ </p>
+ <ul>
+ <li>A Java bean class compatible with the schema description. (If the schema was
+ obtained via Java reflection, then the original Java bean class.)</li>
+ <li>An unmarshaller that converts a conforming XML document into the equivalent Java bean.</li>
+ <li>Vice versa, a marshaller that converts the Java bean back into the original XML document.</li>
+ </ul>
+ <p>
+ In the case of JaxMe, the generated classes may also
+ </p>
+ <ul>
+ <li>Store the Java bean into a database. Preferrably an XML database like
+ <link href="site:exist"><code>eXist</code></link>,
+ <link href="site:xindice"><code>Xindice</code></link>, or
+ <link href="site:tamino"><code>Tamino</code></link>, but it may also
+ be a relational database like <link href="site:mysql"><code>MySQL</code></link>.
+ (If the schema is sufficiently simple. :-)</li>
+ <li>Query the database for bean instances.</li>
+ <li>Implement an EJB entity or session bean with the same abilities.</li>
+ </ul>
+ <p>
+ In other words, by simply creating a schema and running the JaxMe binding
+ compiler,
+ </p>
+ <img src="images/jaxme-compiler-workflow.png" alt="Running the JaxMe 2 compiler"/>
+ <p>
+ you have automatically generated classes that implement the complete
+ workflow of a typical web application:</p>
+ <img src="images/jaxme-application-workflow.png" alt="Workflow of a JaxMe 2 application"/>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/book.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/book.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/book.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/book.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,49 @@
+<?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 book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
+ "http://apache.org/forrest/dtd/book-cocoon-v10.dtd">
+
+<!-- This file is responsible for generating the menu in the 'js' directory.
+ -->
+
+<book software="JaxMeJS" title="JaxMeJS"
+ copyright="@year@ The Apache Software Foundation"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <menu label="JaxMeJS">
+ <menu-item label="Introduction" href="../index.html"/>
+ <menu-item label="The JavaSource factory" href="../factory.html"/>
+ <menu-item label="Writing methods" href="../methods.html"/>
+ <menu-item label="Placeholders" href="../placeholders.html"/>
+ <menu-item label="Optimizations" href="../optimizations.html"/>
+ <menu-item label="Writing SQL" href="../sql.html"/>
+ </menu>
+
+ <menu label="Patterns">
+ <menu-item label="Proxy Objects" href="../patterns/proxy.html"/>
+ <menu-item label="Multiple Inheritance" href="../patterns/proxy.html#multiple_inheritance"/>
+ <menu-item label="Typesafe Enumerations" href="../patterns/typesafeenum.html"/>
+ <menu-item label="Proxy chains" href="../patterns/chains.html"/>
+ <menu-item label="Versioning" href="../patterns/versioning.html"/>
+ </menu>
+
+ <menu label="Applications">
+ <menu-item label="Apache XML-RPC Clients" href="xmlrpc.html"/>
+ </menu>
+</book>
\ No newline at end of file
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/xmlrpc.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/xmlrpc.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/xmlrpc.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/apps/xmlrpc.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,216 @@
+<?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>Apache XML-RPC Clients</title></header>
+ <body>
+ <p>Apache XML-RPC is an implementation of XML-RPC: Remote procedure
+ calls are transmitted as XML documents and the results are returned
+ in the same way.</p>
+ <p>The most important feature of XML-RPC is portability: XML-RPC
+ implementations are available for almost any programming language.
+ The protocol is intentionally restricted to some typical data type,
+ including integers, strings, arrays, and maps.</p>
+ <p>Apache XML-RPC is based on Java reflection: You trade flexibility
+ for type safety and compiler control. But why take the disadvantage?
+ The client generator allows you to have both flexibility and
+ compiler control.</p>
+
+ <section><title>How it works</title>
+ <p>The client generator is roughly similar to the
+ <link href="../patterns/proxy.html">Proxy Generator</link>:
+ Assuming that you have classes A, B, and C on the server,
+ which are being called via XML-RPC, the generator creates
+ classes A', B', and C' with roughly the same set of public
+ methods. The difference is, that the latter classes have
+ every method implemented as an XML-RPC call. However, this
+ XML-RPC call is completely transparent!</p>
+ <p>More precisely, if you have the following class on the
+ server:</p>
+ <source>
+public class Calculator {
+ public int add(int i1, int i2) {
+ return i1 + i2;
+ }
+ public double multiply(double d1, double d2) {
+ return d1 * d2;
+ }
+}
+ </source>
+ <p>The generator will create a class for you, which is roughly
+ similar to:</p>
+ <source>
+public class Calculator {
+ private XmlRpcCaller caller;
+ public Calculator(caller) {
+ this.caller = caller;
+ }
+ public int add(int i1, int i2) {
+ Vector v = new Vector();
+ v.add(new Integer(i1));
+ v.add(new Integer(i2));
+ XmlRpcClient c = new XmlRpcClient(url);
+ Object o = caller.xmlRpcCall("Calculator.add", v);
+ return ((Integer) o).intValue();
+ }
+ public double add(double d1, double d2) {
+ Vector v = new Vector();
+ v.add(new Double(d1));
+ v.add(new Double(d2));
+ Object o = caller.xmlRpcCall("Calculator.add", v);
+ return ((Double) o).doubleValue();
+ }
+}
+ </source>
+ <p>In particular, note that the generated classes are
+ automatically converting from or to primitive types.
+ A basic implementation for the
+ <link href="../../apidocs/org/apache/ws/jaxme/js/apps/XmlRpcCaller.html">
+ XmlRpcCaller</link> would be:</p>
+ <source>
+public class MyCaller implements org.apache.ws.jaxme.js.apps.XmlRpcCaller {
+ private final URL url;
+ public MyCaller(URL url) {
+ this.url = url;
+ }
+ public Object xmlRpcCall(String name, Vector params) throws Exception {
+ return new XmlRpcClient(url).execute(name, params);
+ }
+}
+ </source>
+ </section>
+
+ <section><title>The dispatcher</title>
+ <p>The generator may create one additional class for you, which is
+ dedicated for the server: The dispatcher. In the above example,
+ a dispatcher would be:</p>
+ <source>
+public class Dispatcher implements org.apache.xmlrpc.XmlRpcHandler {
+ public Object execute(String pName, Vector pParams) throws Throwable {
+ if ("Calculator-add".equals(pName)) {
+ int i1 = ((Integer) params.get(0)).intValue();
+ int i2 = ((Integer) params.get(1)).intValue();
+ return new Integer(new Calculator().add(i1, i2));
+ } else if ("Calculator-multiply".equals(pName)) {
+ double d1 = ((Double) params.get(0)).doubleValue();
+ double d2 = ((Double) params.get(1)).doubleValue();
+ return new Double(new Calculator().multiply(d1, d2));
+ }
+ }
+}
+ </source>
+ <p>Note, that the dispatcher may very well be a static final instance
+ variable. It is quite easy, to embed the dispatcher into the server:</p>
+<source>
+ XmlRpcServer xmlrpc = new XmlRpcServer ();
+ xmlrpc.addHandler ("$default", new org.apache.xmlrpc.XmlRpcHandler() {
+ Dispatcher d = new Dispatcher();
+ public Object execute(String pName, Vector pVector) throws Exception {
+ try {
+ return d.invoke(pName, pVector);
+ } catch (Exception e) {
+ throw e;
+ } catch (Throwable t) {
+ throw new UndeclaredThrowableException(t);
+ }
+ }
+ });
+ byte[] result = xmlrpc.execute (request.getInputStream ());
+ response.setContentType ("text/xml");
+ response.setContentLength (result.length());
+ OutputStream out = response.getOutputStream();
+ out.write (result);
+ out.flush ();
+</source>
+ </section>
+
+ <section><title>Using the generator</title>
+ <p>The generator is implemented as an Ant task. A typical invocation will
+ most probably look like this:</p>
+<source>
+ <taskdef resource="org/apache/ws/jaxme/js/pattern/ant.properties"
+ classpathref="js.test.path"/>
+ <xmlRpcGenerator
+ targetPackage="com.foo.xmlrpc.client"
+ destDir="build/src">
+ <dispatcher name="com.foo.xmlrpc.server.Dispatcher"/>
+ <serverClasses dir="src" includes="com/foo/xmlrpc/server/XmlRpc*.java"/>
+ </xmlRpcGenerator>
+</source>
+ <p>The Ant task "xmlRpcGenerator" supports the following attributes:</p>
+ <table>
+ <tr><th>Name</th><th>Description</th><th>Required<br/>Default</th></tr>
+ <tr>
+ <td>classpathRef</td>
+ <td>Specifies a reference to a classpath. This classpath is used,
+ for loading the server classes, if they are passed in as
+ compiled classes and not Java sources.</td>
+ <td>No<br/>Ant path</td>
+ </tr>
+ <tr>
+ <td>destDir</td>
+ <td>Specifies the directory, where sources are being generated.
+ A package structure is created below the directory: If the
+ target package is "com.foo.xmlrpc.client", and the destination
+ directory is "src", then the generated classes will appear in
+ "src/com/foo/xmlrpc/client".</td>
+ <td>No<br/>Current directory</td>
+ </tr>
+ <tr>
+ <td>targetPackage</td>
+ <td>Specifies the package, in which the generated sources are
+ being placed.</td>
+ <td>No<br/>Root package</td>
+ </tr>
+ </table>
+ <p>The Ant task also supports the following nested elements:</p>
+ <table>
+ <tr><th>Name</th><th>Description</th><th>Required<br/>Default</th></tr>
+ <tr>
+ <td>classpath</td>
+ <td>An embedded class path, used as a replacement for the
+ 'classpathref' attribute. Using this nested child element
+ is mutually exclusive with the attribute.</td>
+ <td>No<br/>Ant path</td>
+ </tr>
+ <tr>
+ <td>dispatcher</td>
+ <td>Specifies, that a dispatcher is being generated. The
+ 'name' attribute specifies the dispatchers fully qualified
+ class name.<br/>By default, the dispatcher will implement
+ org.apache.xmlrpc.XmlRpcHandler. This may be suppressed
+ by setting the 'implementingXmlRpcHandler' attribute to
+ false. This is mainly usefull for the JaxMeJS test suite.
+ </td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>serverClasses</td>
+ <td>One or more file sets specifying the server side classes,
+ for which clients are being generated. These classes may either
+ be specified as sources (in which case the
+ <link href="../../apidocs/org/apache/ws/jaxme/js/util/JavaParser.html">
+ Java parser</link> is used for scanning them, or as compiled classes,
+ in which case Java reflection is being used.</td>
+ <td>Yes</td>
+ </tr>
+ </table>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/book.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/book.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/book.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/book.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,50 @@
+<?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 book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
+ "http://apache.org/forrest/dtd/book-cocoon-v10.dtd">
+
+<!-- This file is responsible for generating the menu in the 'js' directory.
+ -->
+
+<book software="JaxMeJS" title="JaxMeJS"
+ copyright="@year@ The Apache Software Foundation"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <menu label="JaxMeJS">
+ <menu-item label="Introduction" href="index.html"/>
+ <menu-item label="The JavaSource factory" href="factory.html"/>
+ <menu-item label="Writing methods" href="methods.html"/>
+ <menu-item label="Placeholders" href="placeholders.html"/>
+ <menu-item label="Optimizations" href="optimizations.html"/>
+ <menu-item label="Writing SQL" href="sql.html"/>
+ <menu-item label="Java Source Reflection" href="jparser.html"/>
+ </menu>
+
+ <menu label="Patterns">
+ <menu-item label="Proxy Objects" href="patterns/proxy.html"/>
+ <menu-item label="Multiple Inheritance" href="patterns/proxy.html#multiple_inheritance"/>
+ <menu-item label="Typesafe Enumerations" href="patterns/typesafeenum.html"/>
+ <menu-item label="Proxy chains" href="patterns/chains.html"/>
+ <menu-item label="Versioning" href="patterns/versioning.html"/>
+ </menu>
+
+ <menu label="Applications">
+ <menu-item label="Apache XML-RPC Clients" href="apps/xmlrpc.html"/>
+ </menu>
+</book>
\ No newline at end of file
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/factory.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/factory.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/factory.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/factory.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.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
+<document>
+ <header><title>Using the JavaSourceFactory</title></header>
+ <body>
+ <p>Using the JavaSource framework is using a
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaSourceFactory.html">JavaSourceFactory</link>.
+ This class is (directly or indirectly) the single access point to all other classes.
+ We demonstrate the basic use with the following example:</p>
+ <source>
+ import java.io.File;
+
+ import javax.xml.parsers.ParserConfigurationException;
+ import javax.xml.parsers.SAXParser;
+ import javax.xml.parsers.SAXParserFactory;
+
+ import org.apache.ws.jaxme.js.JavaMethod;
+ import org.apache.ws.jaxme.js.JavaQName;
+ import org.apache.ws.jaxme.js.JavaQNameImpl;
+ import org.apache.ws.jaxme.js.JavaSource;
+ import org.apache.ws.jaxme.js.JavaSourceFactory;
+
+ public class Test {
+ public static void main(String[] args) throws Exception {
+ // Create a factory
+ JavaSourceFactory factory = new JavaSourceFactory();
+ // Let the factory create a Java source class "com.mycompany.demo.Parser"
+ JavaQName className = JavaQNameImpl.getInstance("com.mycompany.demo", "Parser");
+ JavaSource js = factory.newJavaSource(className, "public");
+ // Add a method "getParser", which instantiates a new SAXParser
+ JavaMethod jm = js.newJavaMethod("getParser", SAXParser.class, "public");
+ jm.setStatic(true);
+ jm.addThrows(ParserConfigurationException.class);
+ jm.addLine(SAXParserFactory.class, " sf = ", SAXParserFactory.class, ".newInstance();");
+ jm.addLine("return sf.newSAXParser();");
+ factory.write(null, factory.getLocation(js));
+ }
+ }
+ </source>
+ <p>The example creates a new class <code>com.mycompany.demo.Parser</code>. The class
+ has a single, static method <code>getParser</code>, which instantiates a new
+ SAX parser. Of couse, you could achieve the same effect much easier with</p>
+ <source>
+ import java.io.File;
+ import java.io.FileWriter;
+
+ public class Test {
+ public static void main(String[] args) throws Exception {
+ FileWriter fw = new FileWriter("com/mycompany/demo/Parser.java");
+ fw.write("package com.mycompany.demo;\n");
+ fw.write("\n");
+ fw.write("import javax.xml.parsers.ParserConfigurationException;\n");
+ fw.write("import javax.xml.parsers.SAXParser;\n");
+ fw.write("import javax.xml.parsers.SAXParserFactory;");
+ fw.write("\n");
+ fw.write("public class Parser {");
+ fw.write(" public SAXParser getParser() throws ParserConfigurationException {\n");
+ fw.write(" SAXParserFactory sf = SAXParserFactory.newInstance();");
+ fw.write(" return sf.newSAXParser();");
+ fw.write(" }");
+ fw.write("}");
+ }
+ }
+ </source>
+ <p>The second example has the obvious advantage that it looks better and simpler.
+ However, it is even larger and you've got to care for indentation,
+ imports and the like. You'll never have a chance to postprocess the generated
+ source, unless you are actually parsing it. That's what the JavaSource framework
+ gives you.</p>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/index.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/index.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/index.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/index.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.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
+<document>
+ <header><title>The JaxMe JavaSource framework</title></header>
+ <body>
+ <section><title>The JaxMe JavaSource framework</title>
+ <p>This is a framework for generating Java sources. It is based on an
+ abstraction of the Java sources. For instance, there is an object called
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaSource.html"><code>JavaSource</code></link>.
+ This object can have embedded instances of
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaMethod.html"><code>JavaMethod</code></link> or
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaField.html"><code>JavaField</code></link>,
+ it can have inner classes, constructors, and so on. You get the idea.
+ Compared to a basic approach of just using <code>Writer.write(String)</code>,
+ the framework has the obvious disadvantage of additional complexity and
+ overhead. However, it also has some advantages:</p>
+ <ol>
+ <li>Your sources become more readable and simpler, for example by
+ automatically importing external classes, if required.</li>
+ <li>Postprocessing the generated sources is much easier. You get
+ the chance to generate sources in multiple steps, or in a pipeline
+ like this:
+ <table><caption>Sourge generation pipeline</caption>
+ <tr>
+ <td>If collection: Generate an iterator loop, otherwise: Skip</td>
+ <td>----></td>
+ <td>Handle the case of a single value</td>
+ </tr>
+ </table>
+ </li>
+ <li>Your generator is much more controlled by the compiler and
+ suitable for refactoring. This is best illustrated by looking at the
+ following example:
+ <source>
+ JavaMethod jm;
+ jm.addLine(MyClass.class, " myInstance = new ", MyClass.class, "();");
+ </source>
+ This example assumes the existance of a class "MyClass". The compiler
+ verifies the existance and a refactoring module might, for example,
+ rename this class.</li>
+ <li>It has a lot of nice shortcuts, for example:
+ <source>
+ addTry();
+ addLine("int i = Integer.parseInt(s);");
+ addCatch(NumberFormatException.class);
+ addThrowNew(IllegalArgumentException.class,
+ JavaSource.getQuoted("Invalid integer argument: "), " + s");
+ addEndTry();
+ </source>
+ </li>
+ </ol>
+ </section>
+
+ <anchor id="history"/>
+ <section><title>History</title>
+ <p>The framework was originally part of the
+ <link href="ext:jaxme1">JaxMe 1</link> generator, the predecessor of
+ <link href="ext:jaxme2">JaxMe 2</link>.
+ It got greatly improved as part on the work of JaxMe 2.
+ Roughly in January 2003 it began to live a live of its own, because the framework
+ was picked up for other projects. So it made sense to separate JaxMeJS in an own
+ jar file and make JaxMe 2 based on it.</p>
+ <p>In a way, the JavaSource framework is still a part of JaxMe, because it lives
+ under the same Apache hat. The sources are located in the same
+ SVN server and the distribution comes from the same file server.
+ The administrators and developers are typically the same. We'll see, what the
+ future brings.</p>
+ </section>
+ </body>
+</document>
+
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/jparser.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/jparser.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/jparser.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/jparser.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,102 @@
+<?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>Java Source Reflection</title></header>
+ <body>
+ <section><title>Why Source Reflection?</title>
+ <p>Java Source Generation is frequently based on reflection. For example,
+ the <link href="patterns/proxy.html">Proxy Generator</link> works
+ roughly like this: Class A is inspected using Java Reflection.
+ A new class B is created. For any public method in A, a method
+ in B is created, that invokes A.</p>
+ <p>This approach has a subtle inconvenience: To use Java reflection,
+ the class A must have already been compiled. As a consequence, the
+ use of generated sources typically happens in three stages:</p>
+ <ol>
+ <li>Compiling a part of the sources</li>
+ <li>Invoking the source generator</li>
+ <li>Compiling the remaining sources</li>
+ </ol>
+ <p>This can become rather nasty. In particular, you cannot reference
+ the second part of the sources from the first part. The build
+ scripts tend to be overly complex and difficult to maintain.</p>
+ <p>Java Source Reflection is a true simplification of the above
+ process: Required informations are gathered from the Java
+ source files, and not from the compiled classes.</p>
+ </section>
+
+ <section><title>How it works</title>
+ <p>Java Source Reflection is implemented by the class
+ <link href="../apidocs/org/apache/ws/jaxme/js/util/JavaParser.html">
+ JavaParser</link>. This class takes as input a Java source file and
+ converts it into an instance of
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaSource.html">
+ JavaSource</link>. The Java parser is internally based on an
+ <link href="ext:antlr">AntLR parser</link>. (AntLR is a public
+ domain parser generator.)</p>
+ <p>The created
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaSource.html">
+ JavaSource</link> instance contains instances of
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaMethod.html">
+ JavaMethod</link>,
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaField.html">
+ JavaField</link>,
+ <link href="../apidocs/org/apache/ws/jaxme/js/JavaInnerClass.html">
+ JavaInnerClass</link>, and so on. Obviously, these can be used to
+ replace classical Java reflection.</p>
+ </section>
+
+ <section><title>Using the JavaParser</title>
+ <p>To use the Java parser, your classpath must obviously contain
+ the file jaxmejs.jar. However, because the actual parser is
+ generated by <link href="ext:antlr">AntLR</link>, you need the
+ file antlr.jar as well. Both files come to you as part of the
+ JaxMe distribution. Besides, a current version of antlr.jar
+ (2.7.4, as of this writing) can always be obtained from
+ <link href="ext:antlr">www.antlr.org</link>. However, if you
+ replace the AntLR parser, then you should probably use the
+ JaxMe source distribution, and rebuild the binaries, thus
+ creating a new parser.</p>
+ <p>The following sample uses Java source reflection to print
+ all public non-static methods of a certain Java class:</p>
+ <source>
+ import org.apache.ws.jaxme.js.*;
+
+ public void printPublicInstanceMethods(File pFile) {
+ JavaSourceFactory jsf = new JavaSourceFactory();
+ JavaParser jp = new JavaParser(jsf);
+ jp.parse(pFile);
+ for (Iterator iter = jsf.getJavaSources(); iter.hasNext(); ) {
+ JavaSource js = (JavaSource) iter.next();
+ System.out.println("Public instance methods of class: " + js.getQName());
+ JavaMethod[] methods = js.getMethods();
+ for (int i = 0; i < methods.length; i++) {
+ if (methods[i].getProtection().equals(JavaSource.PUBLIC) &&
+ !methods[i].isPublic()) {
+ System.out.println(" " + methods[i].getName());
+ }
+ }
+ System.out.println(js.getQName());
+ }
+ }
+ </source>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/methods.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/methods.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/methods.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/methods.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,142 @@
+<?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>Writing methods</title></header>
+ <body>
+ <section><title>Writing methods</title>
+ <p>Generating a method is supported through various shortcuts. These shortcuts and
+ their value are probably best demonstrated by examples.</p>
+ </section>
+
+ <anchor id="throwingExceptions"/>
+ <section><title>Throwing exceptions</title>
+ <p>Throwing exceptions using the standard method <code>addLine()</code>
+ works roughly like this:</p>
+ <source>
+ public JavaMethod getDifficultMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("difficultMethod", "void", "public");
+ jm.addLine("throw new (", NotImplementedException.class, "(",
+ JavaSource.getQuoted("The method 'difficultMethod' is not yet implemented."),
+ ");");
+ return jm;
+ }
+ </source>
+ <p>Using the method <code>addThrowNew()</code>, this could be rewritten as follows:</p>
+ <source>
+ public JavaMethod getDifficultMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("difficultMethod", "void", "public");
+ jm.addThrowNew(NotImplementedException.class,
+ JavaSource.getQuoted("The method 'difficultMethod' is not yet implemented."));
+ return jm;
+ }
+ </source>
+ </section>
+
+ <anchor id="ifBlock"/>
+ <section><title>If .. elseif .. else .. blocks</title>
+ <p>Suggest the following example:</p>
+ <source>
+ public JavaMethod getValueOfMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("valueOf", "int", "public");
+ jm.addParam(String.class, "s");
+ jm.addLine("if (", JavaSource.getQuoted("FOO"), ".equals(s)) {");
+ jm.indent();
+ jm.addLine("return foo;");
+ jm.unindent();
+ jm.addLine("} else if (", JavaSource.getQuoted("BAR"), ".equals(s)) {");
+ jm.indent();
+ jm.addLine("return bar;");
+ jm.unindent();
+ jm.addLine("} else {");
+ jm.indent();
+ jm.addThrowNew(IllegalArgumentException.class,
+ JavaSource.getQuoted("Invalid value for s: "), " + s");
+ jm.unindent();
+ jm.addLine("}");
+ return jm;
+ }
+ </source>
+ <p>This example could also be written like this:</p>
+ <source>
+ public JavaMethod getValueOfMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("valueOf", "int", "public");
+ jm.addParam(String.class, "s");
+ jm.addIf(JavaSource.getQuoted("FOO"), ".equals(s)");
+ jm.addLine("return foo;");
+ jm.addElseIf(JavaSource.getQuoted("BAR"), ".equals(s)");
+ jm.addLine("return bar;");
+ jm.addElse();
+ jm.addThrowNew(IllegalArgumentException.class,
+ JavaSource.getQuoted("Invalid value for s: "), " + s");
+ jm.addEndIf();
+ return jm;
+ }
+ </source>
+ <p>The rewritten example is both shorter and more readable.</p>
+ </section>
+
+ <anchor id="catchBlock"/>
+ <section><title>Try .. catch .. finally .. blocks</title>
+ <p>A try .. catch block is typically written like this:</p>
+ <source>
+ public JavaMethod getAsIntMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("asInt", "int", "public");
+ jm.addParam(String.class, "s");
+ jm.addLine("try {");
+ jm.indent();
+ jm.addLine("return Integer.toString(s);");
+ jm.unindent();
+ jm.addLine("} catch (", NumberFormatException.class, " e) {");
+ jm.indent();
+ jm.addLine("e.printStackTrace();");
+ jm.addLine("return 1;");
+ jm.unindent();
+ jm.addLine("}");
+ return jm;
+ }
+ </source>
+ <p>To simplify the example, use the <code>addTry()</code> and
+ <code>addCatch()</code> methods:</p>
+ <source>
+ public JavaMethod getAsIntMethod(JavaSource pSource) {
+ JavaMethod jm = pSource.newJavaMethod("asInt", "int", "public");
+ jm.addParam(String.class, "s");
+ jm.addTry();
+ jm.addLine("return Integer.toString(s);");
+ jm.addCatch(NumberFormatException.class, "e");
+ jm.addLine("e.printStackTrace();");
+ jm.addLine("return 1;");
+ jm.addEndTry();
+ return jm;
+ }
+ </source>
+ <p>An even shorter version would be to replace</p>
+ <source>
+ jm.addCatch(NumberFormatException.class, "e");
+ </source>
+ <p>with</p>
+ <source>
+ jm.addCatch(NumberFormatException.class);
+ </source>
+ <p>The method version with a single parameter generates a local variable name, which
+ is returned as a result by the <code>addCatch()</code> method.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/optimizations.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/optimizations.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/optimizations.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/optimizations.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,184 @@
+<?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>Optimizations</title></header>
+ <body>
+ <section><title>Optimizations</title>
+ <p>Automatically generated code tends to become unnecessarily
+ complex and unreadable. This page summarizes some optimization
+ concepts offered by JaxMeJS and possible strategies to use them.</p>
+ </section>
+
+ <anchor id="directAccessible"/>
+ <section><title>The DirectAccessible interface</title>
+ <p>In general JaxMeJS deals with objects, in the most general sense.
+ An object can be almost everything: An array or collection containing
+ a piece of code, a variable, method, or class name or whatever else.
+ While this is fine for the most situations, it can become difficult
+ in the following example:</p>
+ <source>
+ Object value;
+ return new Object[]{"((", value, ") * (", value, "))"};
+ </source>
+ <p>The example computes the square of the given "value". This example
+ is obviously fine, if "value" contains a simple variable name or
+ something similar. But how about that:</p>
+ <source>
+ value = "Math.sin(x)";
+ </source>
+ <p>The computation of a sine can become relatively expensive, in particular,
+ if the same computation is performed twice. However, at least the example
+ works, which is no longer the case here:</p>
+ <source>
+ value = "i++";
+ </source>
+ <p>Filling this value in the above example would yield</p>
+ <source>
+ ((i++) * (i++))
+ </source>
+ <p>This is simply wrong, because the variable "i" is incremented twice.
+ The obvious solution is the use of a local Java field, as in the
+ following example:</p>
+ <source>
+ Object value;
+ JavaQName type;
+ LocalJavaField v = method.newJavaField(type);
+ v.setFinal(true);
+ v.addLine(value);
+ return new Object[]{"((", v, ") * (", v, "))"};
+ </source>
+ <p>This is obviously better, as it handles both the performance problem
+ caused by the sine computation and the logical problem caused by the
+ increment. However, if you start using such local fields, your code will
+ soon start to look like the following:</p>
+ <source>
+ String val;
+ String _1 = val;
+ String _2 = _1;
+ </source>
+ <p>Again, this is something we do not actually like to see. JaxMeJS suggests
+ the use of the
+ <link href="../apidocs/org/apache/ws/jaxme/js/DirectAccessible.html">DirectAccessible</link>
+ interface. This is an interface implemented by objects, which are accessible
+ immediately and fast: Class and instance fields, method parameters, and
+ local fields. This allows the following final example:</p>
+ <source>
+ Object value;
+ JavaQName type;
+ if (!(value instanceof DirectAccessible)) {
+ LocalJavaField v = method.newJavaField(type);
+ v.setFinal(true);
+ v.addLine(value);
+ value = v;
+ }
+ return new Object[]{"((", value, ") * (", value, "))"};
+ </source>
+ </section>
+
+ <anchor id="nullChecks"/>
+ <section><title>Avoiding unnecessary checks for null</title>
+ <p>The
+ <link href="../apidocs/org/apache/ws/jaxme/js/DirectAccessible.html">DirectAccessible</link>
+ interface can also be used to avoid situations like this:</p>
+ <source>
+ public void doThis(JavaMethod pMethod, Object pValue) {
+ pMethod.addIf(pValue, " == null");
+ pMethod.addThrowNew(NullPointerException.class, "value must not be null");
+ pMethod.addEndIf();
+ addLine("// Do this here ...");
+ doThat(pMethod, pValue);
+ }
+ public void doThat(JavaMethod pMethod, Object pValue) {
+ pMethod.addIf(pValue, " == null");
+ pMethod.addThrowNew(NullPointerException.class, "value must not be null");
+ pMethod.addEndIf();
+ addLine("// Do that here ...");
+ }
+ </source>
+ <p>If we invoke the method <code>doThis(method, someVariable)</code>, it is
+ creates the following code:</p>
+ <source>
+ if (someVariable == null) {
+ throw new NullPointerException("value must not be null");
+ }
+ // Do this here ...
+ if (someVariable == null) {
+ throw new NullPointerException("value must not be null");
+ }
+ // Do that here ...
+ </source>
+ <p>A better approach would be:</p>
+ <source>
+ public void doThis(JavaMethod pMethod, Object pValue, JavaQName pType) {
+ DirectAccessible value;
+ if (pValue instanceof DirectAccessible) {
+ value = pValue;
+ } else {
+ LocalJavaField foo = pMethod.newJavaField(pType);
+ foo.addLine(pValue);
+ value = foo;
+ }
+ if (value.isNullable()) {
+ pMethod.addIf(pValue, " == null");
+ pMethod.addThrowNew(NullPointerException.class, "value must not be null");
+ pMethod.addEndIf();
+ value.setNullable(false);
+ }
+ addLine("// Do this here ...");
+ doThat(pMethod, pValue, pType);
+ }
+ public void doThat(JavaMethod pMethod, Object pValue, JavaQName pType) {
+ DirectAccessible value;
+ if (pValue instanceof DirectAccessible) {
+ value = pValue;
+ } else {
+ LocalJavaField foo = pMethod.newJavaField(pType);
+ foo.addLine(pValue);
+ value = foo;
+ }
+ if (value.isNullable()) {
+ pMethod.addIf(pValue, " == null");
+ pMethod.addThrowNew(NullPointerException.class, "value must not be null");
+ pMethod.addEndIf();
+ value.setNullable(false);
+ }
+ addLine("// Do that here ...");
+ }
+ </source>
+ <p>In the worst case, this will create the following code:</p>
+ <source>
+ if (someVariable == null) {
+ throw new NullPointerException("value must not be null");
+ }
+ // Do this here ...
+ // Do that here ...
+ </source>
+ <p>Note, that loop variables, as generated by <code>addForArray()</code>,
+ <code>addForIterator</code>, or <code>addForList</code>, will never be
+ nullable. In other words, the following code sequence will emit no checks
+ for null at all:</p>
+ <source>
+ DirectAccessible loopVar = pMethod.addForList(list);
+ pMethod.doThis();
+ pMethod.addEndFor();
+ </source>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/book.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/book.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/book.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/book.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,49 @@
+<?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 book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
+ "http://apache.org/forrest/dtd/book-cocoon-v10.dtd">
+
+<!-- This file is responsible for generating the menu in the 'js' directory.
+ -->
+
+<book software="JaxMeJS" title="JaxMeJS"
+ copyright="@year@ The Apache Software Foundation"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <menu label="JaxMeJS">
+ <menu-item label="Introduction" href="../index.html"/>
+ <menu-item label="The JavaSource factory" href="../factory.html"/>
+ <menu-item label="Writing methods" href="../methods.html"/>
+ <menu-item label="Placeholders" href="../placeholders.html"/>
+ <menu-item label="Optimizations" href="../optimizations.html"/>
+ <menu-item label="Writing SQL" href="../sql.html"/>
+ </menu>
+
+ <menu label="Patterns">
+ <menu-item label="Proxy Objects" href="proxy.html"/>
+ <menu-item label="Multiple Inheritance" href="proxy.html#multiple_inheritance"/>
+ <menu-item label="Typesafe Enumerations" href="typesafeenum.html"/>
+ <menu-item label="Proxy chains" href="chains.html"/>
+ <menu-item label="Versioning" href="versioning.html"/>
+ </menu>
+
+ <menu label="Applications">
+ <menu-item label="Apache XML-RPC Clients" href="../apps/xmlrpc.html"/>
+ </menu>
+</book>
\ No newline at end of file
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/chains.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/chains.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/chains.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/chains.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,167 @@
+<?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>Proxy chains (also known as: Delegator pattern)</title></header>
+ <body>
+ <anchor id="chains"/>
+ <p>The proxy chain is best explained with the situation it was made for.
+ Suggest a really complex source generator with varying options. For example,
+ a child element of an object can have multiplicity zero, one or more: In
+ the latter case the child element will most probably be represented by a
+ list. Quite necessarily the source generator will sonner or later be
+ bloated with statements like</p>
+ <source>
+ if (child.isMultiple()) {
+ // Do something, working with a List
+ ...
+ } else {
+ // Do something else, working with a single element
+ }
+ </source>
+ <p>Even worse, the code will in both cases look quite similar: As soon as the
+ list item is fetched and casted to a proper type, this is just like working
+ with a single item. As time goes by, more and more similar options come into
+ play: Localization, varying datatypes, and so on. Soon you start to think of
+ better solutions.</p>
+ <p>The first attempt is typically subclassing. For example, if you have
+ a source generator for the case multiplicity zero or one, it can well
+ be expanded to the general case, with multiplicity two or more being
+ handled in the subclass. Localization is handled in the next subclass,
+ and so on. Your code looks much better now and becomes maintainable
+ again.</p>
+ <p>However, time goes by, and more options are added to the source generator:
+ Transaction handling, encoding issues, and so on. Soon you find yourself in
+ trouble again: The subclassing approach doesn't work so well anymore, because
+ in a subclass chain E -> D -> C -> B -> A (where B is a subclass of A, C is
+ a subclass of B, and so on) you sometimes want all of them, but sometimes
+ only D -> C -> A or E -> A. At that point of thinking a new approach was born:
+ The event chain.</p>
+ <p>The idea is replacing the subclasses with an event interface. For example,
+ suggest that the source generator might contain code like the following:</p>
+ <source>
+ public class FooGeneratorImpl implements FooGenerator {
+ public JavaSource getFooClass() {
+ JavaSource js = factory.newJavaSource(fooClassName, "public");
+ getXMethod(js);
+ getYMethod(js);
+ getZMethod(js);
+ }
+ ...
+ }
+ </source>
+ <p>The corresponding interface might look like this:</p>
+ <source>
+ public interface FooGenerator {
+ public JavaSource getFooClass();
+ public JavaMethod getXMethod(JavaSource js);
+ public JavaMethod getYMethod(JavaSource js);
+ public JavaMethod getZMethod(JavaSource js);
+ }
+ </source>
+ <p>If you take this methods as events, then you might well write a default
+ class A implementing the interface. The other classes are implemented as
+ subclasses of an automatically generated <link href="proxy.html">proxy class</link>.
+ For example, the class B might just add another method to the <code>Foo</code>.
+ This might look like the following:</p>
+ <source>
+ public class B extends FooGeneratorProxy {
+ // Override only the getFooClass() method, all other methods are
+ // passed to the base generator by the proxy.
+ public JavaSource getFooClass() {
+ JavaSource result = super.getFooClass();
+ JavaMethod bMethod = result.newJavaMethod("bMethod", "void", "public");
+ return result;
+ }
+ }
+ </source>
+ <p>Likewise, the C class might change the interface of method X, and so on.
+ Any feature is implemented by a single class, which you can optionally add
+ to the chain (turning the feature on) or remove from the chain (turning the
+ feature off).</p>
+ <p>However, there's still a problem left: When you are inside A (the topmost
+ class) and do a <code>getXMethod()</code>, then you call your own class and
+ not the chains bottom. This problem is fixed by the following design:</p>
+ <table>
+ <tr>
+ <td colspan="5">Controller</td><td>Implements FooGenerator</td>
+ </tr>
+ <tr>
+ <td>E</td><td>D</td><td>C</td><td>B</td><td>A</td>
+ <td>Implements ChainedFooGenerator</td></tr>
+ </table>
+ <p>The <code>ChainedFooGenerator</code> is exactly matching the
+ <code>FooGenerator</code> interface, the exception being an additional
+ parameter <code>FooGenerator pController</code> in all methods. The
+ FooGenerator interface can be created automatically, also an
+ implementation of FooGenerator calling the first element in the chain of
+ <code>ChainedFooGenerator</code> implementations. The manually created classes
+ have to be changed slightly, here's the updated <code>FooGeneratorImpl</code>:</p>
+ <source>
+ public class FooGeneratorImpl implements ChainedFooGenerator {
+ public JavaSource getFooClass(FooGenerator pController) {
+ JavaSource js = factory.newJavaSource(fooClassName, "public");
+ pController.getXMethod(js);
+ pController.getYMethod(js);
+ pController.getZMethod(js);
+ }
+ ...
+ }
+ </source>
+ <p>Likewise, here is the updated B class:</p>
+ <source>
+ public class B extends ChainedFooGeneratorProxy {
+ // Override only the getFooClass() method, all other methods are
+ // passed to the base generator by the proxy.
+ public JavaSource getFooClass(FooGenerator pController) {
+ JavaSource result = super.getFooClass(pController);
+ JavaMethod bMethod = result.newJavaMethod("bMethod", "void", "public");
+ return result;
+ }
+ }
+ </source>
+ <p>The proxy chain pattern is implemented by the
+ <link href="../../apidocs/org/apache/ws/jaxme/js/pattern/ChainGenerator.html">ChainGenerator</link>.
+ From within Ant, it looks like the following:</p>
+ <source>
+ <chainGenerator destDir="src">
+ <chain
+ controllerInterfaceName="com.dcx.sein.dbtk.generator.javasg.IModelSG"
+ chainInterfaceName="com.dcx.sein.dbtk.generator.javasg.auto.IChainedModelSG"
+ proxyClassName="com.dcx.sein.dbtk.generator.javasg.auto.ChainedModelSGProxy"
+ implementationClassName="com.dcx.sein.dbtk.generator.javasg.auto.ModelSGImpl"/>
+ <chain
+ controllerInterfaceName="com.dcx.sein.dbtk.generator.javasg.IObjectSG"
+ chainInterfaceName="com.dcx.sein.dbtk.generator.javasg.auto.IChainedObjectSG"
+ proxyClassName="com.dcx.sein.dbtk.generator.javasg.auto.ChainedObjectSGProxy"
+ implementationClassName="com.dcx.sein.dbtk.generator.javasg.auto.ObjectSGImpl"/>
+ </chainGenerator>
+ </source>
+ <p>The <code>controllerInterfaceName</code> is the name of the basic interface.
+ This is what you actually want to use from the outside. The controller interface
+ must be available as a compiled class, because it is inspected with Java reflection.
+ The other classes are generated: The <code>chainInterfaceName</code> is the interface
+ being implemented by the manually written classes. The <code>proxyClassName</code>
+ is an automatically generated implementation of the <code>chainInterface</code>,
+ which passes all events to the next element in the chain. And the
+ <code>implementationClassName</code> is an also automatically generated implementation
+ of <code>controllerInterface</code>, that works internally by passing all events
+ to the first element in the chain.</p>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/proxy.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/proxy.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/proxy.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/proxy.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,126 @@
+<?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>Proxy objects</title></header>
+
+ <body>
+ <anchor id="proxy_objects"/>
+ <section><title>Proxy objects</title>
+ <p>A proxy class is a class that implements a list of interfaces specified at
+ compile time. The proxy object typically holds a reference to an internal
+ object that implements the same interfaces (or parts of them). The proxy
+ object is implemented by delegating method calls to the internal object.
+ This is the same principle as implemented by the class
+ <code>java.lang.reflect.Proxy</code>, which created proxy objects dynamically
+ at runtime using Java reflection.</p>
+ <p>Compared to the standard Proxy class, the generator has the obvious
+ disadvantage, that you have to specify the implemented interfaces at runtime.
+ On the other hand, it allows both to select the proxy objects super class and
+ the derivation of subclasses. In fact the derivation of a subclass is much
+ more obvious, simple and faster than the use of an InvocationHandler.</p>
+ <p>The proxy generator is implemented by the class
+ <link href="../../apidocs/org/apache/ws/jaxme/js/pattern/ProxyGenerator.html">ProxyGenerator</link>.
+ Use of the ProxyGenerator is demonstrated in the Ant target "generate.proxy".</p>
+ <p>The proxy generator Ant task supports the following attributes:</p>
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Description</th>
+ <th>Required<br/>Default</th>
+ </tr>
+ <tr>
+ <td>classpathRef</td>
+ <td>Reference to a class path, being used to load Java
+ classes or sources. See the "type" attribute in the
+ nested element "implementedInterface" below for details.
+ Use of the "classpathRef" attribute is mutually exclusive
+ with the nested element "classpath".
+ </td>
+ <td>No<br/>Ant's class path</td>
+ </tr>
+ <tr>
+ <td>destDir</td>
+ <td>Path of the directory, where the generated sources are
+ being created. A package structure will be created below.
+ In other words, if a class "org.apache.Foo" is generated,
+ then it will be found in the file ${destDir}/org/apache/Foo.class.
+ </td>
+ <td>No<br/>Current directory</td>
+ </tr>
+ <tr>
+ <td>extendedClass</td>
+ <td>Specifies the fully qualified name of a class, which is being
+ extended by the generated sources.</td>
+ <td>No<br/>java.lang.Object</td>
+ </tr>
+ </table>
+ <p>The proxy generator Ant task also supports the following nested elements:</p>
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Description</th>
+ <th>Required<br/>Default</th>
+ </tr>
+ <tr>
+ <td>classPath</td>
+ <td>Specifies a path, which is being used for loading
+ Java classes or sources. See the "type" attribute in
+ the nested element "implementedInterface" below for
+ details. The "classpath" element is mutually exclusive
+ with the "classpathRef" attribute.</td>
+ <td>No<br/>Ant's class path</td>
+ </tr>
+ <tr>
+ <td>implementedInterface</td>
+ <td>Specifies an additional interface being implemented.
+ This element must have an attribute "interface" with
+ the fully qualified name of a Java interface which is
+ being implemented by the generated classes.<br/>
+ The generator needs to determine the methods specified
+ by the interface.
+ If the element has an attribute "type" with the value
+ "Reflection", then the specified interface will be
+ loaded as a compiled Java class. Otherwise, if the
+ attribute "type" has the value "Source", then the
+ generator attempts to load a Java source file with
+ the same name from the class path and parse it.
+ Otherwise, if the "type" attribute is missing, it will
+ attempt both "Reflection" and "Source", in that order.
+ </td>
+ <td>
+ Yes, at least one
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <anchor id="multiple_inheritance"/>
+ <section><title>Multiple Inheritance</title>
+ <p>Multiple inheritance is a design pattern which is not so easy to implement
+ in Java - unless you use the
+ <link href="../../apidocs/org/apache/ws/jaxme/js/pattern/ProxyGenerator.html">ProxyGenerator</link>.
+ This is demonstrated by the JUnit test
+ <link href="../../apidocs/org/apache/ws/jaxme/js/junit/MultipleInheritanceTest.html">MultipleInheritanceTest</link>,
+ which creates a subclass of <code>java.util.Observable</code>, that also inherits
+ from <code>java.util.ArrayList</code>. The example implements a list, which
+ notifies its observers whenever the <code>add()</code> method is invoked.</p>
+ </section>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/typesafeenum.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/typesafeenum.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/typesafeenum.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/typesafeenum.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.
+
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
+<document>
+ <header><title>Typesafe enumerations</title></header>
+
+ <body>
+ <p>Typesafe enumerations are classes with a private constructor and only
+ a few defined instances. Each instance does have a name and a value. As
+ of Java 1.5, they will be part of the Java language. For those of us,
+ who are still stuck with older versions, a source generator is a good
+ solution.</p>
+ <source>
+ <enumGenerator targetClass="org.apache.ws.jaxme.js.junit.EnumExample"
+ destDir="${build.src}">
+ <item name="JOE" value="John Doe"/>
+ <item name="POPEYE" value="Olivia's Lover"/>
+ <item name="DONALD" value="The Duck King"/>
+ </enumGenerator>
+ </source>
+ <p>This will generate a class looking roughly like this:</p>
+ <source>
+ public class EnumExample {
+ private String name;
+ private String value;
+ private EnumExample(String pName, String pValue) {
+ name = pName;
+ value = pValue;
+ }
+ public String getName() { return name; }
+ public String getValue() { return value; }
+ public final static EnumExample JOE = new EnumExample("JOE", "John Doe");
+ public final static EnumExample POPEYE = new EnumExample("POPEYE", "Olivia's Lover");
+ public final static EnumExample DONALD = new EnumExample("DONALD", "The Duck King");
+ }
+ </source>
+ <p>The important thing with this enumeration is that there cannot be other
+ instances besides <code>JOE</code>, <code>POPEYE</code> and <code>DONALD</code>.</p>
+ </body>
+</document>
Added: webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/versioning.xml
URL: http://svn.apache.org/viewvc/webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/versioning.xml?view=auto&rev=479221
==============================================================================
--- webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/versioning.xml (added)
+++ webservices/jaxme/trunk/ws-jaxme/src/site/xdoc/js/patterns/versioning.xml Sat Nov 25 14:46:04 2006
@@ -0,0 +1,172 @@
+<?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>The version generator</title></header>
+ <body>
+
+ <anchor id="introduction"/>
+ <section><title>The version generator</title>
+ <p>A versioned object is an object with a composed primary key:
+ We call the first part the version ID and the second part the version number.
+ Objects with the same ID are called versions of the object. If the versioned
+ object is stored in a single SQL table, a new version can obviously be derived
+ as follows:</p>
+ <ol>
+ <li>Read the row containing the base version.</li>
+ <li>Create a copy of the row in memory.</li>
+ <li>Update the version number in the in-memory clone.</li>
+ <li>Insert the clone into the database.</li>
+ </ol>
+ <p>There is nothing special. Things look quite different, if we have multiple
+ tables. For example, suggest that we have a database with the tables
+ "Organization", "Person", and "Email Address". Any organization might have
+ associated persons as contacts. Organizations and persons, however, might
+ have an unlimited number of email addresses. Foreign keys are used to
+ join the different tables. The organization can be viewed as a collection
+ of a row in "Organization" and zero or more rows in "Person". How about
+ creating a new version of an organization? This is not so convenient:</p>
+ <ol>
+ <li>Read the row containing the organization and clone it,
+ following the above steps.</li>
+ <li>The cloned row doesn't have any associated email addresses,
+ but the base organization probably does. In other words, we need
+ to read the relevant email addresses into memory, update the
+ organization reference and create new instances of the in-memory
+ email addresses, possibly creating a new ID.</li>
+ <li>The cloned organization doesn't have any associated persons,
+ but the base organization probably does. You guess the following:
+ We need to clone the persons as well, updating references and
+ assigning new ID's.</li>
+ <li>We are not yet done: The persons might be referenced by email
+ adresses. So we continue ... you guess.</li>
+ </ol>
+ <p>The version generator is able to create Java code for you, which is
+ doing exactly the above. It takes as input a list of tables and an
+ ID generation procedure for any table, and that's it.</p>
+ </section>
+
+ <anchor id="limitations"/>
+ <section><title>Limitations</title>
+ <p>The current version of the version generator has some restrictions. In
+ particular the following rules apply:</p>
+ <ol>
+ <li>Let <code>T1</code>, <code>T2</code>, <code>T3</code>, ... be the
+ tables being cloned.</li>
+ <li>No table may reference itself. For example, <code>T3</code> must
+ not have a reference to <code>T3</code>.</li>
+ <li>No table may have forward references. A forward reference is a
+ foreign key to another table, which is positioned behind itself
+ in the table. For example, <code>T2</code> and <code>T3</code>
+ may reference <code>T1</code>, but neither <code>T2</code> nor
+ <code>T3</code> may reference <code>T1</code> nor may <code>T3</code>
+ reference <code>T2</code>.</li>
+ <li>All foreign keys must reference the primary key. As a consequence,
+ each referenced table must have a primary key.</li>
+ </ol>
+ <p>In essence, the requirements are, that there are no direct or indirect
+ circular references and that there is a set of columns that allow to
+ remember, which rows already have been cloned.</p>
+ </section>
+
+ <anchor id="columnUpdaters"/>
+ <section><title>Column updaters</title>
+ <p>Column updaters are used to perform the required modifications for the
+ in-memory rows. For example, there is a column updater that updates a
+ foreign keys value from an object that has already been cloned to its
+ clone. Column updaters are implementing the interface
+ <link href="../../apidocs/org/apache/ws/jaxme/js/pattern/VersionGenerator.ColumnUpdater.html">
+ VersionGenerator.ColumnUpdater</link>.</p>
+ <p>The main thing to understand when writing a column updater is that it
+ is not invoked at runtime, but as a part of the source generation stage.
+ It emits Java code taking an object array as input and modifying the
+ array. As an example, we demonstrate a very basic column updater,
+ which is simply incrementing the version number. We assume that the
+ version number is an integer, stored in the tables second column:</p>
+ <source>
+ public class VerNumIncrementer implements VersionGenerator.ColumnUpdater {
+ public void update(JavaMethod pMethod,
+ VersionGenerator.TableInfo pTableInfo,
+ DirectAccessible pConnection,
+ DirectAccessible pMap,
+ DirectAccessible pRow) {
+ pMethod.addLine(pRow, "[2] = new Integer(((Integer) ",
+ pRow, "[2]).intValue()+1);");
+ }
+ }
+ </source>
+ <p>The column updaters arguments are as follows:</p>
+ <dl>
+ <dt>pMethod</dt><dd>The method being generated.</dd>
+ <dt>pTableInfo</dt><dd>Holds the generators view of the table being
+ cloned by the method <code>pMethod</code>. The most important property
+ is the <code>table</code> property, which returns an instance of
+ <link href="../../apidocs/org/apache/ws/jaxme/sqls/Table.html">Table</link> with the table name
+ and column list.</dd>
+ <dt>pConnection</dt><dd>A variable name which is holding an open
+ database connection in the generated source.</dd>
+ <dt>pMap</dt><dd>A variable name with a map used to note the column
+ which have already been cloned. The tables keys are the primary keys before cloning,
+ and the tables values are the keys after cloning. The map is used
+ to adjust foreign key references.</dd>
+ <dt>pRow</dt><dd>A variable name representing an array of objects,
+ one for any column in the table. The object types correspond to the
+ column data types: For example, a VARCHAR or CHAR column is mapped
+ to a String, INT, or BIGINT, columns are mapped to Integer and
+ Long, respectively, and so on.</dd>
+ </dl>
+ </section>
+
+ <anchor id="use"/>
+ <section><title>Using the version generator</title>
+ <p>To use the version generator, you need a set of tables (subject to the
+ limitations described <link href="#limitations">above</link>). For any table,
+ you also need a ColumnUpdater. If you have that, the generator is invoked
+ like this:</p>
+ <source><![CDATA[
+ import org.apache.ws.jaxme.js.JavaQNameImpl;
+ import org.apache.ws.jaxme.js.JavaSource;
+ import org.apache.ws.jaxme.js.JavaSourceFactory;
+ import org.apache.ws.jaxme.js.pattern.VersionGenerator;
+ import org.apache.ws.jaxme.js.pattern.VersionGenerator.ColumnUpdater;
+ import org.apache.ws.jaxme.sqls.Table;
+
+ Table[] tables; // Supplied by you
+ ColumnUpdater updaters; // Supplied by you, same length than tables array
+
+ JavaSourceFactory factory = new JavaSourceFactory();
+ VersionGenerator vgen = new VersionGenerator();
+ vgen.setGeneratingLogging(true);
+ for (int i = 0; i < tables.length; i++) {
+ vgen.addTable(tables[i], updaters[i]);
+ }
+ JavaSource js = factory.newJavaSource(JavaQNameImpl.getInstance("com.foo", "Bar"),
+ JavaSource.PUBLIC);
+ vgen.getCloneMethod(js);
+]]> </source>
+ <p>You might replace the VersionGenerator with a subclass, because the above
+ code would emit logging statements using the
+ <link href="../../apidocs/org/apache/ws/jaxme/logging/package-summary.html">
+ org.apache.ws.jaxme.logging package</link>.
+ If you do not favour this, replace the methods <code>logEntering</code>,
+ <code>logExiting</code>, <code>logFinest</code>, <code>logFinestEntering</code>,
+ and <code>logFinestEntering</code> with your own implementations.</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