cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dkazimirc...@apache.org
Subject svn commit: r1176390 - in /cayenne/main/trunk/docs/docbook/getting-started-rop: ./ src/ src/docbkx/ src/images/
Date Tue, 27 Sep 2011 14:07:35 GMT
Author: dkazimirchyk
Date: Tue Sep 27 14:07:35 2011
New Revision: 1176390

URL: http://svn.apache.org/viewvc?rev=1176390&view=rev
Log:
Getting Started with Cayenne ROP docbook

Added:
    cayenne/main/trunk/docs/docbook/getting-started-rop/
    cayenne/main/trunk/docs/docbook/getting-started-rop/pom.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/authentification.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-code.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/index.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part1.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part2.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/setup.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
  (with props)
    cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/warning.gif   (with props)

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/pom.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/pom.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/pom.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/pom.xml Tue Sep 27 14:07:35 2011
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+	Licensed to the Apache Software Foundation (ASF) under one
+	or more contributor license agreements.  See the NOTICE file
+	distributed with this work for additional information
+	regarding copyright ownership.  The ASF licenses this file
+	to you 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.   
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<parent>
+		<groupId>org.apache.cayenne.docs</groupId>
+		<artifactId>cayenne-docbook</artifactId>
+		<version>3.1M4-SNAPSHOT</version>
+	</parent>
+	<modelVersion>4.0.0</modelVersion>
+	<groupId>org.apache.cayenne.docs</groupId>
+	<artifactId>getting-started-rop</artifactId>
+	<name>Docbook: Getting Started with Cayenne ROP</name>
+</project>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/authentification.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/authentification.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/authentification.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/authentification.xml Tue
Sep 27 14:07:35 2011
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Adding BASIC authentication...</title>
+    <para>You probably don't want everybody in the world to connect to your service
and access (and
+        update!) arbitrary data in the database. The first step in securing Cayenne service
is
+        implementing client authentication. The easiest way to do it is to delegate the
+        authentication task to the web container that is running the service. HessianConnection
used
+        in the previous chapter supports BASIC authentication on the client side, so we'll
+        demonstrate how to set it up here.</para>
+    <section xml:id="securing-rop-server-app">
+        <title>Securing ROP Server Application</title>
+        <para>Open web.xml file in the server project and setup security constraints
with BASIC
+            authentication for the ROP service:</para>
+        <programlisting>&lt;security-constraint&gt;
+    &lt;web-resource-collection&gt;
+        &lt;web-resource-name&gt;CayenneService&lt;/web-resource-name&gt;
+        &lt;url-pattern&gt;/cayenne-service&lt;/url-pattern&gt;
+    &lt;/web-resource-collection&gt;
+    &lt;auth-constraint&gt;
+        &lt;role-name&gt;cayenne-service-user&lt;/role-name&gt;
+    &lt;/auth-constraint&gt;
+&lt;/security-constraint&gt;
+    
+&lt;login-config&gt;
+    &lt;auth-method&gt;BASIC&lt;/auth-method&gt;
+    &lt;realm-name&gt;Cayenne Realm&lt;/realm-name&gt;
+&lt;/login-config&gt;
+	
+&lt;security-role&gt;
+    &lt;role-name&gt;cayenne-service-user&lt;/role-name&gt;
+&lt;/security-role&gt;</programlisting>
+    </section>
+    <section xml:id="configuring-jetty">
+        <title>Configuring Jetty for BASIC Authentication</title>
+        <informaltable class="noteMacro">
+            <col width="4%"/>
+            <col width="96%"/>
+            <tbody>
+                <tr>
+                    <td rowspan="1" colspan="1" valign="top">
+                        <mediaobject>
+                            <imageobject>
+                                <imagedata
+                                    fileref="../images/warning.gif"
+                                    depth="16" width="16"/>
+                            </imageobject>
+                        </mediaobject>
+                    </td>
+                    <td rowspan="1" colspan="1">These instructions are specific to
Jetty 6. Other
+                        containers (and versions of Jetty) will have different mechansims
to achieve
+                        the same thing.</td>
+                </tr>
+            </tbody>
+        </informaltable>
+        <para>Open pom.xml in the server project and configure a "userRealm" for the
Jetty
+            plugin:</para>
+        <programlisting>&lt;plugin&gt;
+	&lt;groupId&gt;org.mortbay.jetty&lt;/groupId&gt;
+		&lt;artifactId&gt;maven-jetty-plugin&lt;/artifactId&gt;
+		&lt;version&gt;6.1.22&lt;/version&gt;
+		&lt;!-- adding configuration below: --&gt;
+		&lt;configuration&gt;
+			&lt;userRealms&gt;
+				&lt;userRealm implementation="org.mortbay.jetty.security.HashUserRealm"&gt;
+					&lt;!-- this name must match the realm-name in web.xml --&gt;
+					&lt;name&gt;Cayenne Realm&lt;/name&gt;
+					&lt;config&gt;realm.properties&lt;/config&gt;
+				&lt;/userRealm&gt;
+			&lt;/userRealms&gt;
+		&lt;/configuration&gt;
+	&lt;/plugin&gt;
+&lt;/plugins&gt;</programlisting>
+        <para>Now create a new file called {["realm.properties"}} <emphasis role="italic">at
the
+                root of the server project</emphasis> and put user login/password in
there:</para>
+        <programlisting>cayenne-user: secret,cayenne-service-user</programlisting>
+        <para>.</para>
+        <para>Now let's stop the server and start it again. Everything should start
as before, but
+            if you go to <emphasis role="italic"
+                >http://localhost:8080/tutorial/cayenne-service</emphasis>, your
browser should pop
+            up authentication dialog. Enter "<emphasis role="italic">cayenne-user/secret</emphasis>"
+            for user name / password, and you should see "<emphasis role="italic">Hessian
Requires
+                POST</emphasis>" message. So the server is now secured.</para>
+    </section>
+    <section xml:id="running-client">
+        <title>Running Client with Basic Authentication</title>
+        <para>If you run the client without any changes, you'll get the following error:</para>
+        <programlisting>Jan 16, 2010 6:09:03 PM org.apache.cayenne.remote.hessian.HessianConnection
connect
+INFO: Connecting to [http://localhost:8080/tutorial/cayenne-service] - dedicated session.
+Jan 16, 2010 6:09:03 PM org.apache.cayenne.remote.hessian.HessianConnection connect
+INFO: Error establishing remote session. URL - http://localhost:8080/tutorial/cayenne-service;

+CAUSE - cannot retry due to server authentication, in streaming mode
+java.net.HttpRetryException: cannot retry due to server authentication, in streaming mode
+	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1034)
+	at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:367)
+	at com.caucho.hessian.client.HessianProxy.invoke(HessianProxy.java:168)
+	at $Proxy0.establishSession(Unknown Source)
+	at org.apache.cayenne.remote.hessian.HessianConnection.connect(HessianConnection.java:210)
+	at org.apache.cayenne.remote.hessian.HessianConnection.getServerEventBridge(HessianConnection.java:114)
+	at org.apache.cayenne.remote.ClientChannel.setupRemoteChannelListener(ClientChannel.java:256)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:94)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:76)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:71)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:67)
+	at org.example.cayenne.persistent.client.Main.main(Main.java:25)
+Exception in thread "main" org.apache.cayenne.CayenneRuntimeException: [v.3.0RC1 Jan 05 2010
14:44:59] Error 
+establishing remote session. URL - http://localhost:8080/tutorial/cayenne-service; 
+CAUSE - cannot retry due to server authentication, in streaming mode
+	at org.apache.cayenne.remote.hessian.HessianConnection.connect(HessianConnection.java:229)
+	at org.apache.cayenne.remote.hessian.HessianConnection.getServerEventBridge(HessianConnection.java:114)
+	at org.apache.cayenne.remote.ClientChannel.setupRemoteChannelListener(ClientChannel.java:256)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:94)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:76)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:71)
+	at org.apache.cayenne.remote.ClientChannel.&lt;init&gt;(ClientChannel.java:67)
+	at org.example.cayenne.persistent.client.Main.main(Main.java:25)
+Caused by: java.net.HttpRetryException: cannot retry due to server authentication, in streaming
mode
+	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1034)
+	at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:367)
+	at com.caucho.hessian.client.HessianProxy.invoke(HessianProxy.java:168)
+	at $Proxy0.establishSession(Unknown Source)
+	at org.apache.cayenne.remote.hessian.HessianConnection.connect(HessianConnection.java:210)
+	... 7 more</programlisting>
+        <para>Which is exactly what you'd expect, as the client is not authenticating
itself. So
+            change the line in Main.java where we obtained an ROP connection to this:</para>
+        <programlisting>ClientConnection connection = new HessianConnection(
+		"http://localhost:8080/tutorial/cayenne-service",
+ "cayenne-user", "secret", null);</programlisting>
+        <para>Try running again, and everything should work as before. Obviously in
production
+            environment, in addition to authentication you'll need to use HTTPS to access
the server
+            to prevent third-party evesdropping on your password and data.</para>
+        <para>Congratulations, you are done with the ROP tutorial!</para>
+    </section>
+</chapter>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-code.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-code.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-code.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-code.xml Tue Sep
27 14:07:35 2011
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Porting existing code to connect to a web service instead of a database...</title>
+    <section xml:id="starting-command-line-cliet">
+        <title>Starting Command Line Client</title>
+        <para>One of the benefits of ROP is that the client code is no different from
the server
+            code - it uses the same ObjectContext interface for access, same query and commit
API.
+            So the code below will be similar to the code presented in the first Cayenne
+                Getting Started Guide, although with a few ROP-specific parts required to
bootstrap the
+            ObjectContext.</para>
+        <para>Let's start by creating an empty Main class with the standard main()
method in the
+            client project:</para>
+        <programlisting>package org.example.cayenne.persistent.client;
+
+public class Main {
+
+	public static void main(String[] args) {
+
+	}
+}</programlisting>
+        <para>Now the part that is actually different from regular Cayenne - establishing
the server
+            connection and obtaining the ObjectContext:</para>
+        <programlisting>ClientConnection connection = new HessianConnection("http://localhost:8080/tutorial/cayenne-service");
+DataChannel channel = new ClientChannel(connection);
+ObjectContext context = new CayenneContext(channel);</programlisting>
+        <para>Note that the "channel" can be used to create as many peer ObjectContexts
as needed
+            over the same connection, while ObjectContext is a kind of isolated "persistence
+            session", similar to the server-side context. A few more notes. Since we are
using
+            HTTP(S) to communicate with ROP server, there's no need to explicitly close the
+            connection (or channel, or context).</para>
+        <para>So now let's do the same persistent operaions that we did in the first
tutorial "Main"
+            class. Let's start by creating and saving some objects:</para>
+        <programlisting>// creating new Artist
+Artist picasso = context.newObject(Artist.class);
+picasso.setName("Pablo Picasso");
+
+// Creating other objects
+Gallery metropolitan = context.newObject(Gallery.class);
+metropolitan.setName("Metropolitan Museum of Art");
+
+Painting girl = context.newObject(Painting.class);
+girl.setName("Girl Reading at a Table");
+
+Painting stein = context.newObject(Painting.class);
+stein.setName("Gertrude Stein");
+
+// connecting objects together via relationships
+picasso.addToPaintings(girl);
+picasso.addToPaintings(stein);
+
+girl.setGallery(metropolitan);
+stein.setGallery(metropolitan);
+
+// saving all the changes above
+context.commitChanges();</programlisting>
+        <para>Now let's select them back:</para>
+        <programlisting>// SelectQuery examples
+SelectQuery select1 = new SelectQuery(Painting.class);
+List&lt;Painting&gt; paintings1 = context.performQuery(select1);
+
+Expression qualifier2 = ExpressionFactory.likeIgnoreCaseExp(
+		Painting.NAME_PROPERTY, "gi%");
+SelectQuery select2 = new SelectQuery(Painting.class, qualifier2);
+List&lt;Painting&gt; paintings2 = context.performQuery(select2);</programlisting>
+        <para>Now, delete:</para>
+        <programlisting>Expression qualifier = ExpressionFactory.matchExp(Artist.NAME_PROPERTY,
+				"Pablo Picasso");
+SelectQuery selectToDelete = new SelectQuery(Artist.class, qualifier);
+Artist picasso = (Artist) DataObjectUtils.objectForQuery(context,
+		selectToDelete);
+
+if (picasso != null) {
+	context.deleteObject(picasso);
+	context.commitChanges();
+}</programlisting>
+        <para>This code is exactly the same as in the first tutorial. So now let's
try running the
+            client and see what happens. In Eclipse open main class and select "Run &gt;
Rus As &gt;
+            Java Application" from the menu (assuming the ROP server started in the previous
step is
+            still running). You will some output in both server and client process consoles.
+            Client:</para>
+        <programlisting>INFO: Connecting to [http://localhost:8080/tutorial/cayenne-service]
- dedicated session.
+INFO: === Connected, session: org.apache.cayenne.remote.RemoteSession@9e09a4[sessionId=10qsakj1mj806]
- took 219 ms.
+INFO: --- Message 0: Bootstrap
+INFO: === Message 0: Bootstrap done - took 71 ms.
+INFO: --- Message 1: flush-cascade-sync
+INFO: === Message 1: flush-cascade-sync done - took 1342 ms.
+INFO: --- Message 2: Query
+INFO: === Message 2: Query done - took 58 ms.
+INFO: --- Message 3: Query
+INFO: === Message 3: Query done - took 21 ms.
+INFO: --- Message 4: Query
+INFO: === Message 4: Query done - took 22 ms.
+INFO: --- Message 5: Query
+INFO: === Message 5: Query done - took 16 ms.
+INFO: --- Message 6: Query
+INFO: === Message 6: Query done - took 2 ms.
+INFO: --- Message 7: Query
+INFO: === Message 7: Query done - took 2 ms.
+INFO: --- Message 8: Query
+INFO: === Message 8: Query done - took 2 ms.
+INFO: --- Message 9: flush-cascade-sync
+INFO: === Message 9: flush-cascade-sync done - took 30 ms.</programlisting>
+        <para>As you see client prints no SQL statmenets, just a bunch of query and
flush messages
+            sent to the server. The server side is more verbose, showing the actual client
queries
+            executed against the database:</para>
+        <programlisting>...
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'GALLERY']
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'ARTIST']
+INFO: SELECT NEXT_ID FROM AUTO_PK_SUPPORT WHERE TABLE_NAME = ? FOR UPDATE [bind: 1:'PAINTING']
+INFO: --- will run 3 queries.
+INFO: INSERT INTO GALLERY (ID, NAME) VALUES (?, ?)
+INFO: [batch bind: 1-&gt;ID:200, 2-&gt;NAME:'Metropolitan Museum of Art']
+INFO: === updated 1 row.
+INFO: INSERT INTO ARTIST (DATE_OF_BIRTH, ID, NAME) VALUES (?, ?, ?)
+INFO: [batch bind: 1-&gt;DATE_OF_BIRTH:NULL, 2-&gt;ID:200, 3-&gt;NAME:'Pablo
Picasso']
+INFO: === updated 1 row.
+INFO: INSERT INTO PAINTING (ARTIST_ID, GALLERY_ID, ID, NAME) VALUES (?, ?, ?, ?)
+INFO: [batch bind: 1-&gt;ARTIST_ID:200, 2-&gt;GALLERY_ID:200, 3-&gt;ID:200, 4-&gt;NAME:'Girl
Reading at a Table']
+INFO: [batch bind: 1-&gt;ARTIST_ID:200, 2-&gt;GALLERY_ID:200, 3-&gt;ID:201, 4-&gt;NAME:'Gertrude
Stein']
+INFO: === updated 2 rows.
+INFO: +++ transaction committed.
+INFO: --- will run 1 query.
+INFO: --- transaction started.
+INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0
+INFO: === returned 2 rows. - took 15 ms.
+INFO: +++ transaction committed.
+INFO: --- will run 1 query.
+INFO: --- transaction started.
+INFO: SELECT t0.GALLERY_ID, t0.ARTIST_ID, t0.NAME, t0.ID FROM PAINTING t0 WHERE UPPER(t0.NAME)
LIKE UPPER(?) [bind: 1-&gt;NAME:'gi%']
+INFO: === returned 1 row. - took 9 ms.
+INFO: +++ transaction committed.
+INFO: --- will run 1 query.
+INFO: --- transaction started.
+INFO: SELECT t0.DATE_OF_BIRTH, t0.ID, t0.NAME FROM ARTIST t0 WHERE t0.NAME = ? [bind: 1-&gt;NAME:'Pablo
Picasso']
+INFO: === returned 1 row. - took 7 ms.
+INFO: +++ transaction committed.
+INFO: --- will run 2 queries.
+INFO: --- transaction started.
+INFO: DELETE FROM PAINTING WHERE ID = ?
+INFO: [batch bind: 1-&gt;ID:200]
+INFO: [batch bind: 1-&gt;ID:201]
+INFO: === updated 2 rows.
+INFO: DELETE FROM ARTIST WHERE ID = ?
+INFO: [batch bind: 1-&gt;ID:200]
+INFO: === updated 1 row.
+INFO: +++ transaction committed.</programlisting>
+        <para>You are done with the basic ROP client!</para>
+    </section>
+</chapter>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-project.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-project.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-project.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/client-project.xml Tue
Sep 27 14:07:35 2011
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Starting client project...</title>
+    <section xml:id="create-rop-client-project">
+        <title>Create an ROP Client Project in Eclipse</title>
+        <para>Creation of a new Eclipse project has been discussed in some details
<link
+                xlink:href="http://cayenne.apache.org/doc30/tutorial-starting-project.html"
+                >here</link>, so we will omit the screenshots for the common parts.</para>
+        <para>In Eclipse select "File &gt; New &gt; Other..." and then "Maven
&gt; Maven Project".
+            Click "Next". On the following screen check "Create a simple project" checkbox
and click
+            "Next" again. In the dialog shown on the screenshot below, enter "org.example.cayenne"
+            for the "Group Id" and "tutorial-rop-client" for the "Artifact Id" (both without
the
+            quotes) and click "Finish". </para>
+        <para>Now you should have a new empty project in the Eclipse workspace. Check
that the
+            project Java compiler settings are correct. Rightclick on the "tutorial-rop-client"
+            project, select "Properties &gt; Java Compiler" and ensure that "Compiler
compliance
+            level" is at least 1.5 (some versions of Maven plugin seem to be setting it to
1.4 by
+            default).</para>
+    </section>
+    <section xml:id="create-client-java-classes">
+        <title>Create Client Java Classes</title>
+        <para>The client doesn't need the XML ORM mapping, as it is loaded from the
server. However
+            it needs the client-side Java classes. Let's generate them from the existing
+            mapping:</para>
+        <itemizedlist>
+            <listitem>
+                <para>Start CayenneModeler and open cayenne.xml from the "tutorial"
project (located
+                    under "tutorial/src/main/resources", unless it is already open.</para>
+            </listitem>
+            <listitem>
+                <para>Select the "UntitledDomainMap" DataMap and check "Allow Client
Entities"
+                    checkbox.</para>
+            </listitem>
+            <listitem>
+                <para>Enter "org.example.cayenne.persistent.client" for the "Client
Java Package"
+                    and click "Update.." button next to the field to refresh the client package
of
+                    all entities.</para>
+                <para><inlinemediaobject>
+                        <imageobject>
+                            <imagedata fileref="../images/datamap-enableclient.png" scalefit="1"
width="100%"/>
+                        </imageobject>
+                    </inlinemediaobject></para>
+            </listitem>
+        </itemizedlist>
+        <itemizedlist>
+            <listitem>
+                <para>Select "Tools &gt; Generate Classes" menu.</para>
+            </listitem>
+            <listitem>
+                <para>For "Type" select "Client Persistent Objects".</para>
+            </listitem>
+            <listitem>
+                <para>For the "Output Directory" select "tutorial-rop-client/src/main/java"
folder
+                    (as client classes should go in the <emphasis role="italic">client</emphasis>
+                    project).</para>
+            </listitem>
+            <listitem>
+                <para>Click on "Entities" tab and check the "Check All Entities" checkbox
(unless it
+                    is already checked and reads "Uncheck all Entities").</para>
+            </listitem>
+            <listitem>
+                <para>Click "Generate".</para>
+            </listitem>
+        </itemizedlist>
+        <para>Now go back to Eclipse, right click on "tutorial-rop-client" project
and select
+            "Refresh" - you should see pairs of classes generated for each mapped entity,
same as on
+            the server. And again, we see a bunch of errors in those classes. Let's fix it
now by
+            adding two dependencies, "cayenne-client" and "resin-hessian", in the bottom
of the
+            pom.xml file. We also need to add Caucho M2 repository to pull Hessian jar files.
The
+            resulting POM should look like this:</para>
+        <programlisting>&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"&gt;
+	&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+	&lt;groupId&gt;org.example.cayenne&lt;/groupId&gt;
+	&lt;artifactId&gt;tutorial-rop-client&lt;/artifactId&gt;
+	&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
+
+	&lt;dependencies&gt;
+		&lt;dependency&gt;
+			&lt;groupId&gt;org.apache.cayenne&lt;/groupId&gt;
+			&lt;artifactId&gt;cayenne-client&lt;/artifactId&gt;
+   &lt;!-- Here specify the version of Cayenne you are actually using --&gt;
+			&lt;version&gt;3.0RC2&lt;/version&gt;
+		&lt;/dependency&gt;
+		&lt;dependency&gt;
+			&lt;groupId&gt;com.caucho&lt;/groupId&gt;
+			&lt;artifactId&gt;resin-hessian&lt;/artifactId&gt;
+			&lt;version&gt;3.1.6&lt;/version&gt;
+		&lt;/dependency&gt;
+	&lt;/dependencies&gt;
+
+	&lt;repositories&gt;
+		&lt;repository&gt;
+			&lt;id&gt;caucho&lt;/id&gt;
+			&lt;name&gt;Caucho Repository&lt;/name&gt;
+			&lt;url&gt;http://caucho.com/m2&lt;/url&gt;
+			&lt;layout&gt;default&lt;/layout&gt;
+			&lt;snapshots&gt;
+				&lt;enabled&gt;false&lt;/enabled&gt;
+			&lt;/snapshots&gt;
+			&lt;releases&gt;
+				&lt;enabled&gt;true&lt;/enabled&gt;
+			&lt;/releases&gt;
+		&lt;/repository&gt;
+	&lt;/repositories&gt;
+&lt;/project&gt;</programlisting>
+        <para>Your computer must be connected to the internet. Once you save the pom.xml,
Eclipse
+            will download the needed jar files and add them to the project build path. After
that
+            all the errors should disappear.</para>
+        <para>Now let's check the entity class pairs. They look almost identical to
their server
+            counterparts, although the superclass and the property access code are different.
At
+            this point these differences are somewhat academic, so let's go on with the
+            tutorial.</para>
+    </section>
+</chapter>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/index.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/index.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/index.xml Tue Sep 27 14:07:35
2011
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
+    xml:id="getting-started-rop" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <info>
+        <title>Getting Started with Cayenne ROP (Remote Object Persistence)</title>
+        <copyright>
+            <year>2011</year>
+            <holder>Apache Software Foundation and individual authors</holder>
+        </copyright>
+        <authorgroup>
+            <author>
+                <personname>Aristedes Maniatis</personname>
+            </author>
+            <author>
+                <personname>Andrus Adamchik</personname>
+            </author>
+        </authorgroup>
+        <legalnotice>
+            <title>License</title>
+            <para>Licensed to the Apache Software Foundation (ASF) under one or more
contributor
+                license agreements. See the NOTICE file distributed with this work for additional
+                information regarding copyright ownership. The ASF licenses this file to
you 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</para>
+            
+            <para>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.</para>
+        </legalnotice>
+    </info>
+    <xi:include href="part1.xml"/>
+    <xi:include href="part2.xml"/>
+</book>
+

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part1.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part1.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part1.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part1.xml Tue Sep 27 14:07:35
2011
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
+    xml:id="getting-started-rop-part1" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <title>Prerequisites...</title>
+    <xi:include href="setup.xml"/>
+</part>
+

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part2.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part2.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part2.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/part2.xml Tue Sep 27 14:07:35
2011
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
+    xml:id="getting-started-rop-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <title>Remote Object Persistence Quick Start</title>
+    <xi:include href="client-project.xml"/>
+    <xi:include href="web-service.xml"/>
+    <xi:include href="client-code.xml"/>
+    <xi:include href="authentification.xml"/>
+</part>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/setup.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/setup.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/setup.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/setup.xml Tue Sep 27 14:07:35
2011
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Prerequisites...</title>
+    <para>This tutorial starts where "Getting Started with Cayenne" left
+        off. If you have gone through the previous tutorial, and have the "tutorial" project
open in
+        Eclipse, you can go directly to the 
+        next step. If not, here are the compressed instructions to prepare you for work
+        with ROP:</para>
+    <itemizedlist>
+        <listitem>
+            <para>
+                Step 1 - Eclipse Setup
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Step 2 - Create a project
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+               Step 3 - Create Cayenne OR Mapping
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Step 4 - Create Java Classes
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Step 5 - Convert the project to webapp.</para>
+        </listitem>
+    </itemizedlist>
+    <para>Note that at "Step 5" you can skip the JSP creation part. Just setup web.xml
and
+        maven-jetty-plugin in the POM.</para>
+</chapter>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/web-service.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/web-service.xml?rev=1176390&view=auto
==============================================================================
--- cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/web-service.xml (added)
+++ cayenne/main/trunk/docs/docbook/getting-started-rop/src/docbkx/web-service.xml Tue Sep
27 14:07:35 2011
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <title>Setting up Hessian web service...</title>
+    <section xml:id="setting-up-dependencies">
+        <title>Setting up Dependencies</title>
+        <para>Now lets get back to the "tutorial" project that contains a web application
and set up
+            dependencies. The only extra one that we don't have yet is resin-hessian.jar,
just like
+            the client, so let's add it (and the caucho repo declaration) to the pom.xml.</para>
+        <programlisting>&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"&gt;
+	...
+	&lt;dependencies&gt;
+		...
+		&lt;dependency&gt;
+			&lt;groupId&gt;com.caucho&lt;/groupId&gt;
+			&lt;artifactId&gt;resin-hessian&lt;/artifactId&gt;
+			&lt;version&gt;3.1.6&lt;/version&gt;
+		&lt;/dependency&gt;
+	&lt;/dependencies&gt;
+
+	&lt;build&gt;
+	...
+	&lt;/build&gt;
+	
+	&lt;repositories&gt;
+		&lt;repository&gt;
+			&lt;id&gt;caucho&lt;/id&gt;
+			&lt;name&gt;Caucho Repository&lt;/name&gt;
+			&lt;url&gt;http://caucho.com/m2&lt;/url&gt;
+			&lt;layout&gt;default&lt;/layout&gt;
+			&lt;snapshots&gt;
+				&lt;enabled&gt;false&lt;/enabled&gt;
+			&lt;/snapshots&gt;
+			&lt;releases&gt;
+				&lt;enabled&gt;true&lt;/enabled&gt;
+			&lt;/releases&gt;
+		&lt;/repository&gt;
+	&lt;/repositories&gt;
+&lt;/project&gt;</programlisting>
+        <informaltable class="noteMacro">
+            <col width="4%"/>
+            <col width="96%"/>
+            <tbody>
+                <tr>
+                    <td rowspan="1" colspan="1" valign="top">
+                        <mediaobject>
+                            <imageobject>
+                                <imagedata fileref="../images/warning.gif" depth="16"
width="16"/>
+                            </imageobject>
+                        </mediaobject>
+                    </td>
+                    <td rowspan="1" colspan="1"><emphasis role="bold">Maven Optimization
+                            Hint</emphasis>On a real project both server and client
modules will
+                        likely share a common parent pom.xml where common repository delcaration
can
+                        be placed, with child pom's "inheriting" it from parent. This would
reduce
+                        build code duplication.</td>
+                </tr>
+            </tbody>
+        </informaltable>
+    </section>
+    <section xml:id="client-classes-on-server">
+        <title>Client Classes on the Server</title>
+        <para>Since ROP web service requires both server and client persistent classes,
we need to
+            generate a second copy of the client classes inside the server project. This
is a minor
+            inconvenience that will hopefully go away in the future versions of Cayenne.
<emphasis
+                role="italic">Don't forget to refresh the project in Eclipse after class
generation
+                is done.</emphasis></para>
+    </section>
+    <section xml:id="configuring-web-xml">
+        <title>Configuring web.xml</title>
+        <para>Cayenne web service is declared in the web.xml. It is implemented as
a servlet
+            "org.apache.cayenne.remote.hessian.service.HessianServlet". Open
+            tutorial/src/main/webapp/WEB-INF/web.xml in Eclipse and add a service declaration:
</para>
+        <programlisting>&lt;?xml version="1.0" encoding="utf-8"?&gt;
+ &lt;!DOCTYPE web-app
+   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"  "http://java.sun.com/dtd/web-app_2_3.dtd"&gt;
+&lt;web-app&gt;
+	&lt;display-name&gt;Cayenne Tutorial&lt;/display-name&gt;
+	&lt;servlet&gt;
+		&lt;servlet-name&gt;cayenne-service&lt;/servlet-name&gt;
+		&lt;servlet-class&gt;org.apache.cayenne.remote.hessian.service.HessianServlet&lt;/servlet-class&gt;
+	&lt;/servlet&gt;
+	&lt;servlet-mapping&gt;
+		&lt;servlet-name&gt;cayenne-service&lt;/servlet-name&gt;
+		&lt;url-pattern&gt;/cayenne-service&lt;/url-pattern&gt;
+	&lt;/servlet-mapping&gt;
+&lt;/web-app&gt;</programlisting>
+        <informaltable class="noteMacro">
+            <col width="4%"/>
+            <col width="96%"/>
+            <tbody>
+                <tr>
+                    <td rowspan="1" colspan="1" valign="top">
+                        <mediaobject>
+                            <imageobject>
+                                <imagedata fileref="../images/warning.gif" depth="16"
width="16"/>
+                            </imageobject>
+                        </mediaobject>
+                    </td>
+                    <td rowspan="1" colspan="1"><emphasis role="bold">Extending
Server Behavior via
+                            Callbacks</emphasis>While no custom Java code is required
on the server,
+                        just a service declaration, it is possible to customizing server-side
+                        behavior via callbacks and listeners (not shown in the tutorial).</td>
+                </tr>
+            </tbody>
+        </informaltable>
+    </section>
+    <section xml:id="running-rop-server">
+        <title>Running ROP Server</title>
+        <para>Use previosly
+                created Eclipse Jetty run configuration available via "Run &gt; Run
+            Configurations..." (or create a new
+                one if none exists yet). You should see output in the Eclipse console similar
+            to the following:</para>
+        <programlisting>[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Building Cayenne Tutorial
+[INFO] 
+[INFO] Id: org.example.cayenne:tutorial:jar:0.0.1-SNAPSHOT
+[INFO] task-segment: [jetty:run]
+[INFO] ------------------------------------------------------------------------
+...
+[INFO] [jetty:run]
+[INFO] Configuring Jetty for project: Cayenne Tutorial
+[INFO] Webapp source directory = /Users/andrus-tutorial/Desktop/work/tutorial/src/main/webapp
+...
+[INFO] Starting jetty 6.1.22 ...
+2010-01-16 17:22:16.906:INFO::jetty-6.1.22
+2010-01-16 17:22:17.027:INFO::No Transaction manager found - if your webapp requires one,
please configure one.
+INFO: started configuration loading.
+INFO: loaded domain: UntitledDomain
+INFO: loaded &lt;map name='UntitledDomainMap' location='UntitledDomainMap.map.xml'&gt;.
+INFO: loading &lt;node name='UntitledDomainNode' datasource='UntitledDomainNode.driver.xml'

+factory='org.apache.cayenne.conf.DriverDataSourceFactory' 
+schema-update-strategy='org.apache.cayenne.access.dbsync.CreateIfNoSchemaStrategy'&gt;.
+INFO: using factory: org.apache.cayenne.conf.DriverDataSourceFactory
+INFO: loading driver information from 'UntitledDomainNode.driver.xml'.
+INFO: loading driver org.apache.derby.jdbc.EmbeddedDriver
+INFO: loading user name and password.
+INFO: Created connection pool: jdbc:derby:memory:testdb;create=true 
+	Driver class: org.apache.derby.jdbc.EmbeddedDriver
+	Min. connections in the pool: 1
+	Max. connections in the pool: 1
+INFO: loaded datasource.
+INFO: no adapter set, using automatic adapter.
+INFO: loaded map-ref: UntitledDomainMap.
+INFO: finished configuration loading in 549 ms.
+2010-01-16 17:22:17.960:INFO::Started SelectChannelConnector@0.0.0.0:8080</programlisting>
+        <para>Cayenne ROP service URL is <emphasis role="italic"
+                >http://localhost:8080/tutorial/cayenne-service</emphasis>. If you
click on it, you
+            will see "Hessian Requires POST" message, that means that the service is alive,
but you
+            need a client other than the web browser to access it.</para>
+    </section>
+</chapter>

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png?rev=1176390&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/datamap-enableclient.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/warning.gif
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/warning.gif?rev=1176390&view=auto
==============================================================================
Binary file - no diff available.

Propchange: cayenne/main/trunk/docs/docbook/getting-started-rop/src/images/warning.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream



Mime
View raw message