samples-sandbox/words-sample/demoscript.html - aries - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Demonstrating the Word Association application</title>
 <style type="text/css">
 body
 {
 font-family:"sans-serif";
 }
 .instruction
 {
 font-style: italic;

 }
 p.dialogue
 {
 }
 .code
 {
 background-color:#e5e5e5;
 font-family:"Courier", "monospace";
 white-space:pre}
 p.field
 {
 font-family:"Courier", "monospace";
 }
 p.command
 {
 font-family: "Courier", "monospace";
 white-space: pre;
 font-weight: bold;
 }
 .xml
 {
 font-family:"Courier", "monospace";
 color:green;
 white-space:pre;
 }
 h2
 {
 color:white;
 background-color:#003366;
 }
 .template
 {
 color:blue;
 }
 .menu
 {
 font-weight: bold;s
 }
 </style>
 </head>
 <body>
 <h1>Demonstrating the Word Association application</h1>
 <p>
 The Word Association application shows a very simple
 example of a realistic
 application architecture. The intention is that it can be coded up
 from scratch in front of a live audience, rather than that it
 demonstrate best practices or more complex patterns. A reference
 copy of the finished application is included with these instructions.
 </p>

 <p>The word association application is so trivial that it may
 seem like a pretty contrived example. After all, no one would actually bother <i>write</i>
 a word association web app, would they? </p>

 <p>Apparently, if it can be done, <a href="http://www.wordassociation.org">someone's already done it:</a></p>

 <img src="www-wordassocation-org.gif" width="500"/>

 <p>Things can go wrong in unexpected ways in live demos, so do have a
 practice run before trying to write the words application
 in front of other people. I've known of people who practice the live
 coding parts of their demos twenty times before a presentation, although
 that might be a bit too much preparation for most of us! The <a href="#troubleshooting">
 troubleshooting tips</a> may help debug common problems. A working copy of the application is provided
 for reference, so you can refer to it if things go slightly wrong, or swap
 in pre-built bundles for broken bundles if things go very wrong.
 </p>

 <p>Italicized text is instructions to the person giving the demo. Most
 of the rest of the text of this document is a sample script
 for a demo.</p>

 <h2>Pre-demo set-up</h2>

 <h3>Assembly set-up</h3>

 This should be done before starting the demo. Build the words-assembly
 project using maven. The target directory provides an assembly into which the words
 jars can be loaded and run.


 <h3>IDE set-up</h3>

 <h4>IBM Rational Tools for OSGi Applications</h4>
 <p>The instructions assume the free version of the IBM Rational Tools for OSGi Applications are being used. The demo will work fine without them, but some of the steps
 for project creation and project export will be different. Follow these <a href="http://www.ibm.com/developerworks/rational/downloads/10/rationaldevtoolsforosgiapplications.html">instructions for
 installing the tools</a> (or use Eclipse marketplace). Try to get comfortable
 with using the ctrl-space content assist for almost all your typing
 - it will speed the process of producing the code and xml up considerably.
 </p>

 <h4>Setting ${java_home}</h4>


 <p>You'll need to add a variable called java_home. Go to <b>Window&rarr;Preferences&rarr;Run/debug&rarr;String substitution</b> and add
 a variable called java_home which points to your java home.
 </p>

 <h3>Database set-up</h3>

 <p>The database will be automatically created when the words-assembly build is run.
 It can be found in the target directory of the words-assembly project after it has been built.
 </p>

 <p>The words-assembly includes a datasource bundle already.
 This is a minor sleight-of-hand, but coding up the datasource
 in front of a live audience and ensuring it loads before the
 jpa bundle doesn't add much value pedagogically.
 </p>

 <h3>Workspace set-up</h3>

 <p>You can make some changes in your workspace beforehand which will make the demo
 faster. What works well is deleting the created projects at the end of a demo
 but keeping the actual workspace so that the templates and builders can be re-used.
 </p>

 <p> You'll need to be using the JEE perspective or some
 of the instructions won't make sense,
 so switch to that perspective before the demo. </p>

 <h4>Templates</h4>

 <p>The application has the minimum necessary amount of code,
 but it's possibly still more than you'll want to type in front
 of an audience. There are two strategies for avoiding the typing.
 One is to dual-head the laptop and keep a file on the non-projected
 screen from which you can cute and paste. The other is to set up
 some eclipse templates.</p>

 <p class="instruction">Navigate to Preferences&rarr;Java&rarr;Editor&rarr;Templates. Select Import, and choose java-templates.xml.
 You should get three new templates, dopost, doget, and webform.
 </p>

 <p class="instruction">Navigate to Preferences&rarr;XML&rarr;XMLFiles&rarr;Editor&rarr;Templates. Select Import, and choose xml-templates.xml.
 You should get three new templates, recorder, lister, and jpans.
 </p>

 <h4>Target platform</h4>

 <p>We need some plugins which don't ship with the Eclipse WTP
 platform by default, and want to ensure we don't introduce
 dependencies on bundles which aren't in our
 assembly. We do this by defining a new target platform.</p>

 <p class="instruction">Navigate to <span class="menu">Window&rarr;Preferences</span>
 and then navigate to <span class="menu">Plug-in development&rarr;Target platform</span>.
 Select the <span class="menu">Add...</span> button,
 accept the Initialize with 'nothing' option on the next panel.
 Choose <span class="menu">Add...</span> again on the Target Content
 panel, accept the 'Directory' default in the list,
  and browse to the
 words-assembly/target directory. Choose <span class="menu">Finish</span>.
 The words-assembly should show in the list, with
 around 40 plugins. Make sure all the plugins are selected. (If the list of plugins is empty,
 build the words-assembly and then choose <span class="menu">Reload</span>.
 Click <span class="menu">OK</span>, and you should now
 have a list of target platforms which includes your new platform.
 Select it so that it is checked as the default target platform.</p>

 <h4>Entity enhancement</h4>


 <p>
 If you're running in a JEE-5-application server, JPA entities will be automatically enhanced.
 We're just running in a little OSGi container, so we need to do that ourselves.Normally an ant task would be used to enhance the entities when building,
 but it can also be done
  using
 an eclipse builder. Most of the work to set up the builder can be done
 in advance.

 </p>

 <p class="instruction">In your workspace, select External Tools from the
 toolbar. (It's the play icon with what looks like a little red suitcase on it.)
 Select External tool configurations ... from the menu,
 highlight Program in the panel on the left of the wizard, and then
 click the new icon from the toolbar within the wizard (it's the
 white rectangle with the little yellow cross in the corner).</p>


 <p>Fill in JPA_enhancer for the name. Move to the Location field and fill in the full path to the java executable,
 as follows:</p>

 <p class="field">${java_home}/jre/bin/java</p>

 <p class="instruction">Fill in the following in the Arguments box:</p>

 <p class="field">-cp ${target_home}/openjpa-all-2.0.0.jar:${build_project}/src org.apache.openjpa.enhance.PCEnhancer ${build_files}</p>


 (The variables will be filled in by eclipse when the enhancer builder run.)
 </p>

 <h3>JPA library</h3>

 <p>Eclipse needs to be told where to find the JPA implementation. The easiest way to
 do this is create a new OSGI project. (We'll delete it at the end.)</p>

 <p class="instruction">Create a new OSGi bundle project by bringing up a context menu in the package explorer and selecting <strong>New&rarr;Other&rarr;OSGi&rarr;OSGi Bundle Project.</strong>, and choose a JPA facet.
 Type 'eraseme' for the name, and accept the defaults for everything else. Click next
 and keep clicking next until you get to the panel called JPA facet (about three panels in).
 </p>

 <p class="instruction">The platform should be Generic 2.0 and the type should be
 User Library. Create a library by clicking on the little book icon to the right
 of the list of libraries. Click <strong>New</strong>, fill in jpa_library for the name, and click <strong>OK</strong>.
 With the new jpa_library library highlighted, click the <strong>Add jars</strong>
 button, and navigate to the geronimo-jpa_2.0_spec-1.0.jar (it will be in your words-assembly).
 Accept the defaults for the other parameters and finish. Even after deleting the eraseme project, the
 library will be saved in your workspace for re-use. (Don't delete the eraseme project until you've
 set up the launch configuration.)
 </p>


 <h3>Launch configuration</h3>

 <p>The words jars can be run in two ways, either by exporting them and adding them
 to the assembly and launching an OSGi framework from the command line, or
 by running the projects within Eclipse. Running within eclipse is faster
 and usually looks better for the demo. </p>

 <p>Copy the "Words launch configuration.launch" file into the eraseme project and refresh.
 </p>
 <p>
 Navigate to the <b>Run</b> icon (the large green arrow on the toolbar), bring
 up the dropdown menu, and select <b>Run configurations...</b>. The Words
 launch configuration should be listed in under OSGi Frameworks. Verify that
 all the plugins in the target platform are selected. Navigate to the Arguments
 tab, and confirm that the arguments include:
 </p>

 <p class="code"/>
       -Dorg.osgi.framework.system.packages.extra=javax.transaction;version=1.1.0,javax.transaction.xa;version=1.1.0 -Xbootclasspath/p:${target_home}/geronimo-jta_1.1_spec-1.1.1.jar
 </p>
 <p>
 This ensures the OSGi framework exported the JTA packages at version 1.1, which is the version expected by Apache Aries, and the second thing it does is add the extra classes onto the JVM boot classpath.</p>
 On the same tab, the working directory should be ${target_home}. </p>

 <p>Finally, you need to ensure the launch configuration survives when you
 delete the eraseme project. To do this, navigate to the Common tab and change
 the radio button from <i>Shared file</i> to <i>Local file</i>.
 </p>

 <p>Delete the eraseme project (including its contents on disk) and make sure that
 the Words launch configuration is still available in the Run configurations menu.
 </p>

 <h3>Set-up verification</h3>

 <p>
 This demo involves a lot of live coding, so there is a possibility
 of things going wrong. In the event of demo accidents, it may be best
 to swap in the 'official' version of the problem jar or project. Of course,
 you'll want to confirm the
 official versions will work before starting. The official versions can
 be used in two ways, either on the command line, or as eclipse projects
 launched within eclipse. </p>

 <h4>Running on the command line (less cool-looking)</h4>
 <p>Copy
 all the words bundles - <i>except for the datasource jar</i> - into the load directory of the words-assembly
 directory.
 </p>
 <p class="command">
 cd words-assembly/target
 mkdir load
 cp ../../words-api/target/*.jar load
 cp ../../words-web/target/*.jar load
 cp ../../words-jpa/target/*.jar load
 </p>

 <p class="instruction">
 Launch the OSGi container (from words-assembly/target).
 </p>

 <p class="command">
 java -jar osgi-3.5.0.v20090520.jar -clean -console
 </p>

 <p>Confirm that <a href=http://localhost:8080/words-web/AssociateWord>http://localhost:8080/words-web/AssociateWord</a>
 URL works.
 </p>

 <p>Don't forget to remove the official jars before the demo starts - but do
 keep them somewhere handy for emergencies. A directory called backup in the target
 directory is a good place.</p>

 <h4>Running within eclipse (better-looking)</h4>

 <p>Within Eclipse, right click to bring up the context menu and chose <b>Import&rarr;Import&rarr;General&rarr;Existing projects into workspace</b>.
 Make sure the <b>Select root directory</b> radio button is selected and browse to the words-sample directory.
 Select all the projects except the the words-datasource project. Make sure that the
 Copy projects into workspace option is selected and import.
 </p>
 <p>
 <p>You can also import the eclipse projects into your workspace, which will add them
 to the launch configuration.</p>


 <h3>Finally ...
 </h3>

 <p>The first time you practice the demo, it may take an long time. It may seem like you'll never manage to write a whole web application in a short enough time. However, with a few practice runs you should get pretty quick at it.
 It should be possible to do the whole demo in around half an hour, or less if you
 pre-can some parts of some of the bundles.
 </p>

 <p>
 Do remember to print out a copy of these instructions to take with you during the demo.</p>
 <h2>The demo</h2>

 <h3>Setting the scene</h3>

 <p class="dialogue">We're going to write a web application which plays a game of
 word association with a user. The application has three components - there's a web
 front end, a back end which handles the data and persistence using JPA. We want the
 front end and back end to be loosely coupled, so there's a third component which is
 a set of shared APIs.
 </p>

 <p class="instruction">It can be helpful to show the following architecture diagram:</p>

 <img src="architecture.gif"></img>

 <p class="dialogue">What we're going to be running the application on is a little
 OSGi
 container embedded in Eclipse. Aries can also sit on top of a full JEE server, like Geronimo, and
 that's probably a more typical way of using it. </p>

 <p>It should be possible to do the whole of the demo without restarting the OSGi console.</p>

 <h4>The IDE</h4>

 <p class="dialogue">What we need to do now is create the bundles which make up our application.
 A bundle is a jar which some extra-metadata, and so it's easy to create using your
 favourite IDE. Eclipse has lots of OSGi support, and there's also a set of free tools
 which have extra support for Aries, so I'll be using those, but all of this can easily
 be done in another IDE, with base eclipse, or on the command line for the very hardcore.</p>


 <p class="dialogue">We start off with a shared API. We want everything to be loosely coupled, so
 we'll have a bundle with interfaces.
 </p>

 <p class="instruction">Right click, <b>New&rarr;Other&rarr;OSGi&rarr;OSGi Bundle project</b> (or type OSG in the box to filter).
 Fill in the name words.api and click Finish.
 </p>

 <p class="dialogue">We're going to play a game of word assocation,
 so we need a service that gives us a word to associate with.
 </p>

 <p class="instruction">Right click on the newly created project, do <b>New&rarr;Interface</b>, and
 </p>
 <p style="field">
 Package: org.apache.words
 Name: WordGetterService.
 </p>
 Add the following method:

 <p class="code">        String getRandomWord();
 </p>

 <p class="dialogue">We'll also want to do some sort of analysis on what associations people make, so
  we'll add an association recorder service.
 </p>

 <p class="instruction">
 Right click on the newly created project, do <b>New&rarr;Interface</b>, and
 </p>
 <p style="field">
 Package: org.apache.words
 Name: AssociationRecorderService.
 </p>

 <p class="instruction">Add the following method:
 </p>
 <p class="code">        void recordAssociation(String word, String association);
 </p>

 <p class="dialogue">It's no use making a note of what associations have been made if we can't access
  that data, so we'll add one more method:</p>

 <p class="code">        String getLastAssociation(String word);
 </p>

 <p class="dialogue">The default in OSGi is for classes to be private to a bundle, but this is an API, so we
 declare that everyone can use these interfaces. </p>

 <p class="instruction">Double-click on the manifest, click on the runtime tab, and click Add.
 Select the words package. Select manifest tab to show the change which has been made.</p>

 <p class="dialogue">Making that package visible externally is just a question of adding a line in the bundle manifest. </p>

 <h4>Export (not needed if using the launch configuration)</h4>

 <p class="instruction">Finish off by exporting the bundle. Right click on
 the project, choose Export, and then navigate to OSGi&rarr;OSGi Bundle.
 Choose the load directory of your assembly for the export location
 and click Finish. Go back to the OSGi console and type ss again.
 The new bundle should have appeared in the framework. The GOAT
 tool could also be used to show the bundle appearing.</p>

 <h3>The web bundle</h3>

 <p class="dialogue">Now that we have our interfaces for our services,
 we're going to create our web front-end.</p>
 <p class="instruction">Make the project for the web front end. Right click, New&rarr;Other&rarr;OSGi&rarr;OSGi Bundle project.
 Fill in the name words-web
 Select 'OSGi Web Configuration' from the configuration drop-down.
 Click Finish.
 </p>

 <p class="instruction">
 Expand the Deployment Descriptor twistie. (If it's not there, make
 sure you're in the JEE perspective.)
 </p>
 <p class="instruction">Right-click on Servlets to create a new servlet.
 </p>
 <p class="instruction">Enter the following.
 </p>

 <p class="field">
 package name: org.apache.words.web
 <br/>
 class name: AssociateWord
 </p>

 <p class="dialogue">Click Finish. It will auto-create the servlet. </p>

 <p class="dialogue">There will be compile errors.
 This is the first point at which we're starting to see it's OSGi.
 Normally, we'd have to change the eclipse classpath to add the javax.servlet jar. Well, that's actually the second step. First of all we'd have to work out what
  jar the HttpServlet class is in.
  How many of you have got good at doing 'grep -r' on your system to figure out what jar a class is in?
 </p>

 <p class="dialogue">In this case, we just declare that we're have a dependency on the javax.servlet
 and javax.servlet.http packages. To do that, we open our manifest and enter it as a dependency. Eclipse will even give us content completion, but we can also enter it by hand on the manifest
 </p>
 <p class="instruction">Expand WebContent&rarr;META-INF&rarr;MANIFEST.MF and double click.
 Add the package to the top-right box on the dependencies tab.
 </p>

 <p class="dialogue">We're also going to want to use our api, so we'll add that dependency now too.
 </p>

 <p class="instruction">Click Add, enter *word* and select the words package.
 Switch tabs to show the change which has been made to the manifest.
 Then navigate back to the AssociateWord class
 </p>

 <p class="dialogue">We need to fill in some html boilerplate in the doGet() method
 so that our servlet sends back some html.
 </p>

 <p class="instruction">Type 'dog', hit ctrl-space, and select the <span class="template">doget</span> template from
 the content assist. You should now have the following code:</p>

 <p class="code">        PrintWriter out = response.getWriter();
         out.println("&lt;html&gt;");
         out.println("&lt;/html&gt;");
 </p>

 <p class="dialogue">What our servlet will do is prompt the user
 with a random word which it gets from the word getter service. </p>

 <p class="instruction">Navigate to between the two lines for the html
 element creation and fill in the html to print out the random word:
 </p>

 <p class="code">                WordGetterService getter = null;
 				String randomWord = getter.getRandomWord();
 				out.println("The word is " + randomWord);
 </p>

 <p class="dialogue">
 So do you think this is going to work? I don't think so either - we're using a service,
 but we haven't written any implementation for it. We better put some failsafes in.
 </p>

 <p class="instruction">Add guards around the getter dereference:</p>

 <p class="code">            if (getter != null)
             {
 </p>
 and

 <p class="code">            } else
             {
                 out.println("Oh dear. Our dependencies haven't been found.");
             }
 </p>

 <p class="dialogue">
 Now we've given the user a word, and we want them to give us back a word they
 associate with it. We do this with html input.
 </p>

 <p class="instruction">Move the cursor back to below the out.println which prints the random word and add the following using the <span class="template">webform</span> content assist template.</p>

 <p class="code">
 			out.println("<br/>);
 			out.println("&lt;form action=\"AssociateWord\" method=\"post\"&gt;");
 			out.println("What do you associate with "
 					+ randomWord
 					+ "?	    &lt;input type=\"text\" name=\"association\" /&gt; &lt;br /&gt;    ");
 			out.println("&lt;input type=\"hidden\" name=\"word\" value=\""
 					+ randomWord + "\"/&gt;");
 			out.println("&lt;input type=\"submit\" name=\"Submit\"/&gt;");
 			out.println("&lt;/form&gt;");

 </p>
 <p class="dialogue">When the user submits the form, we want to tell them what other things have
 been associated with that word.
 </p>
 <p class="instruction">
 Add the following content to the doPost() method using the <span class="template">dopost</span> template:
 </p>
 <p class="code">                String word = request.getParameter("word");
                 String association = request.getParameter("association");

 				AssociationRecorder recorder = null;
                 String previousAssociation = null;
                 if (recorder != null) {
                         previousAssociation = recorder.getLastAssociation(word);
                         recorder.recordAssociation(word, association);
                 }
                 PrintWriter out = response.getWriter();
                 out.println("The last person associated " + word + " with "
                                 + previousAssociation);
 </p>

 <p class="instruction">You can now try it out using the launch configuration.
 If you navigate to <a href=http://localhost:8080/words-web/AssociateWord>http://localhost:8080/words-web/AssociateWord</a>
 and there should be a message about missing dependencies.
 </p>

 <p class="dialogue">Now we've got a basic web front end. However,
 we're relying on services and we haven't done anything to
 get those services. There are three ways we can get our services. One is the normal OSGi way of looking them up in a bundle context. Aries adds the possibility of dependency injection,
 and also a JEE-integration which allows looking them up in JNDI.
 Blueprint dependencies can't be injected into a servlet, because a servlet
 is a JEE kind of artefact and we don't control its lifecycle - this is the same as you get with spring,
 dependency injection doesn't work with spring.  Instead we'll look them up in JNDI. This is
 the first thing we're doing which is specific to Aries. Normally you
 can have a JEE bundle, or you can have an OSGi bundle, but there's not
 much integration between the two. Here Aries is providing a compatibility
 layer between the servlet, which is managed by the JEE container, and
 all the great OSGi services we're going to want to use.</p>

 <p class="instruction">
 </p>

 <p class="dialogue">This is an OSGi bundle, and InitialContext isn't shipped as an OSGi bundle,
 so we need to add Import-Package: javax.naming. We could also use @Resource here.
 </p>

 <p class="instruction">Navigate back to the manifest and add a dependency
 on javax.naming.
 </p>

 <p class="instruction">Add the following code to the beginning of the doGet() method
 (after declaring the getter variable). You'll also need to set the getter to be null
 when you declare it. It may be easier to not type the try-catch and add it in by using ctrl-1
 while hovering over the compile-error:
 </p>

 <p class="code">		try {
 			getter = (WordGetterService) new InitialContext()
 					.lookup("aries:services/"
 							+ WordGetterService.class.getName());
 		} catch (NamingException e) {
 			e.printStackTrace();
 		}
 </p>

 <p class="code">AssociationRecorder recorder = null;
 			try {
 			recorder = (AssociationRecorderService) new InitialContext()
 					.lookup("aries:services/"
 							+ AssociationRecorderService.class.getName());
 		} catch (NamingException e) {
 			e.printStackTrace();
 		}
 </p>

 <p>(It may be worth defining a template for these pieces of code as well - there's
 more argument for typing them out in full since they're conceptually quite
 important.)
 </p>

 <p class="instruction">Launching the launch configuration and navigating to <a href="http://localhost:8080/words-web/AssociateWord">http://localhost:8080/words-web/AssociateWord</a>words
 should bring up a web page that's blank. There will be lots of stack traces
 about the missing dependencies since that's how we chose to handle our missing
 dependencies - perhaps not the best technique!

 <h3>The persistence</h3>

 <p>The JPA project is the most complex project and you may wish to pre-create
 part of the project - for example, the base project, the manifest, and the persistence.xml
 definitions.</p>

 <p class="instruction">Create another OSGi bundle project, call it words-jpa, and choose a JPA facet. The <strong>Finish</strong>
 button should be enabled.
 </p>
 <p class="instruction">(If the finish button isn't enabled, click through until prompted to choose a library on the JPA facet panel.
 Select the jpa_library library you created earlier. Accept the defaults for the other parameters and finish.)
 </p>

 <p class="dialogue">This new project is going to implement the words
 services, so We need to add a dependency on the words API.
 </p>

 <p class="instruction">Navigate to the manifest, and add the package which comes up if you type *word* into the filter box.
 </p>

 <p class="dialogue">Note that *word* doesn't show any code from our web bundle, because we wanted to
  keep that private.
 </p>

 <h4>Setting up the persistence</h4>

 <h5>Entity enhancement</h5>

 <p class="dialogue">If you're running in a JEE-5-application server, JPA entities will be automatically enhanced. We're just running in a little OSGi container, so we need to do that ourselves. Normally you'd use an ant task to enhance the entities, but we're running
 in Eclipse, so we'll add an eclipse builder.
 </p>

 <p class="instruction">Right-click on the project, select Properties, choose Builders,
 then Import. Choose the JPA launcher you defined earlier. You should see the following message in the console following each build:
 </p>
 <p class="field" style="color: red;">132  words-jpa  INFO   [main] openjpa.Tool - No targets were given.  Running on all classes in your persistent classes list, or all metadata files in classpath directories if you have not listed your persistent classes.  Use -help to display tool usage information.
 </p>

 <h5>Package dependencies</h5>

 <p class="instruction">You will also need to add some package dependencies. Add depencies on javax.persistence,
 org.apache.openjpa.enhance, and org.apache.openjpa.util.</p>

 <p class="code">
 Import-Package: javax.persistence,
  org.apache.openjpa.enhance,
  org.apache.openjpa.util,
  org.apache.words
  </p>

 <h4>Defining the entity</h4>

 <h5>Defining the entities using tooling</h5>

 <p class="instruction">Right-click on the words-jpa project and choose <b>New&rarr;Entity</b>.
 Fill in org.apache.words.jpa for the package and Association for the class name. Choose <b>Next</b> and add 'word' and 'associated' entity fields.
 Use 'String' as the type and 'word' and 'associated' as the names. (Make sure to use associated and not association as the field name!)</p>

 <p class="instruction">There will be a compile error because there is no primary key, so add a primary key for the word field:
 </p>
 <p class="code">        @Id
         private String word;
 </p>

 <p class="dialogue">
 Now we get a compilation error, because we have a dependency on org.apache.openjpa.enhance.
 Normally we'd have to work out which jar this came from and add it to the classpath,
 and if we're sharing the project adding the jar to the classpath in a portable
 way is a bit of a nuisance. Instead we can just add the org.apache.openjpa.enhance package
 to our dependencies.
 </p>

 <p class="instruction">
 Navigate to the manifest and add an import-package for org.apache.openjpa.enhance.
 </p>

 <h4>Setting up the persistence</h4>

 <p class="instruction">
 Expand the newly created project, expand JPA content, and
 open persistence.xml. On the general tab, make sure the Association
 class is on the list of managed classes, and <emph>you must make sure</emph> 'exclude unlisted classes' is selected.
 Navigate to the Connection tab and fill in the following (as a JTA data source):
 </p>
 <p class="field">aries:services/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/wordsdb)
 </p>

 <p class="dialogue">
 Here we're again making use of the JNDI integration Aries provides
 to point JPA at the JNDI mapping of a datasource we've defined
 as an OSGi service.
 </p>

 <p class="dialogue">
 We want to declare the services, and we do this by creating an xml
 file with the service definitions in it.
 </p>

 <p class="instruction">Create a blueprint.xml by New&rarr;Other&rarr;OSGi&rarr;blueprint.xml
 or right-clicking on the project and choosing <strong>OSGi&rarr;Create a new blueprint file</strong>
 </p>

 <p class="dialogue">
 We now need to fill in some namespaces manually, to indicate that we're
 not just going to be using this blueprint.xml for dependency injection -
 we're going to use to get integration with our transaction and persistence
 providers so that they get injected too. We do this by adding the following namespace to our blueprint xml.
 </p>

 <p class="instruction">Navigate to the <span class="code">blueprint</span> element
 and use ctrl-space to bring up the content assist, and choose the <span class="template">jpans</span>
 template. It should fill in the following:</p>

 <p class="xml">xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0" xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"
 </p>


 <p class="dialogue">The blueprint.xml file is one of the most important
 files in an Aries application. It's where we declare dependency injections,
 container-managed persistence, and container-managed transactions.
 It also allows us to create services declaratively. Normally an OSGi service
 would be registered at runtime, by Java code, but that doesn't
 have a very enterprise feel to it. What Aries allows us to do is
 register services declaratively in XML instead.</p>

 <p class="instruction">Add a bean and service definition for the
 association recorder using the <span class="template">recorder</span>
 template. You should end up with the following:</p><p class="xml">	&lt;service interface="org.apache.words.AssociationRecorderService"
 		ref="recorder" /&gt;
 	&lt;bean class="org.apache.words.jpa.Recorder" id="recorder"&gt;
 		&lt;jpa:context property="entityManager" unitname="words-jpa" /&gt;
 		&lt;tx:transaction method="*" value="Required" /&gt;
 	&lt;/bean&gt;
 	&lt;service&gt;
 </p>

 <p class="instruction">The unit name should match the one defined in persistence.xml.
 </p>


 <h4>Defining the recorder service</h4>

 <p class="instruction">Define a new class org.apache.words.jpa.Recorder which
 implements the AssociationRecorderService. Use the new class wizard to fill in
 stubs for the interface methods.

 </p>

 <p class="instruction">Create a field for the entity manager
 and right click, choose <strong>Source&rarr;Generate getters and setters</strong>
 and generate a setter (but no getter).</p>

 <p class="code">
     private EntityManager entityManager;
 </p>

 <p class="code">
     public void setEntityManager(EntityManager entityManager) {
       this.entityManager = entityManager;
     }
 </p>

 <p class="dialogue">
 The cool thing here is that we didn't have to do anything to initialize the
 JPA entity manager - it gets injected for us. Now we just need to fill in
 the logic to handle persisting our data.
 </p>

 <p class="instruction">Fill in the following contents for recordAssociation()
 using the <span class="template">recordAssociation</span> template.
 </p>

 <p class="code">		Association found = entityManager.find(Association.class, word);
 		if (found != null) {
 			found.setAssociated(association);
 		} else {
 			Association a = new Association();
 			a.setWord(word);
 			a.setAssociated(association);
 			entityManager.persist(a);
 		}
 </p>

 <p class="instruction">and getLastAssociation() using the <span class="template">getLastAssociation</span> template
 </p>

 <p class="code">		Association found = entityManager.find(Association.class, word);
 		if (found != null) {
 			return found.getAssociated();
 		} else {
 			return "nothing";
 		}
 </p>


 <h4>The word lister</h4>

 <p class="dialogue">Finally, we need to provide a service which returns
 words to make the associations with. We could have this service backed by
 a database, but it would look pretty similar to the recorder service, so
 for testing we'll just use a static list instead.</p>

 <p class="instruction">Navigate back to the blueprint.xml and add
 a declaration for the service using the <span class="template"">lister</span>
 template. You should end up with the following:</p>

 <p class="xml">
 	&lt;service interface="org.apache.words.WordGetterService"&gt;
 		&lt;bean class="org.apache.words.jpa.WordLister" /&gt;
 	&lt;/service&gt;
 	</p>

 <p class="instruction">Create a WordLister class, have it implement WordGetterService in the class
 creation wizard and fill in the following content around the boiler-plate. You can ask
 the audience to supply the three words to keep them awake.</p>

 <p class="code">public class WordLister implements WordGetterService {
 	String[] words = { "computers", "Java", "coffee" };

 	public WordLister() {
 	}

 	@Override
 	public String getRandomWord() {
 		return words[new Random().nextInt(words.length)];
 	}

 </p>

 <h4>Testing</h4>

 <p class="instruction">Launch the launch configuration.
 Revisiting the web application URL should bring up a web application
 which handles both prompting for a word association and
 telling users what previous users came up with. Making the associations
 should provide another opportunity for people in the audience to
 get involved by calling out word associations.</p>

 <h2>Extras</h2>

 <p>For a longer demo, consider some of the following.
 </p>

 <h3>Application assembly</h3>

 <p>If there's time, we can assemble our bundles into an application.
 The free tools provide support for this. Create a new project of type OSGi Enterprise
 Application, provide a name and choose Next, and then add the words bundles
 to it as a contained bundles and export.
 </p>

 <h3>Multiple lister services</h3>

 <p>We can add a second bundle with a different lister service and show how we can switch
 between the two bundles using the OSGi console.
 </p>

 <h2 id="troubleshooting">Common errors</h2>

 <ul>
 <li>Spelling 'association' 'assocation', 'assciaton', or 'associaton' - or numerous other variants!</li>
 <li>Making a dependency on the bundle instead of the package</li>
 <li>Shortening package names. It's temping to use shorter package names while coding live. Doing this is risky
  because it means the canned bundles can't be swapped in to replace bundles which don't work quite right after being coded in front of an audience.
  </li>
  <li>Split packages. If shorter package names are used, a different short package name must be used for each bundle or blueprint will struggle to resolve things.</li>
 <li>Forgetting build-time JPA enhancement. This leads to the following runtime error: ""This configuration disallows runtime optimization, but the following listed types were not enhanced at build time or at class load time with a javaagent".
 To resolve, make sure the OpenJPA plugin is installed in eclipse and add the
  bytecode enhancer to the JPA project.</li>
  <li>Anonymous beans for JPA services. Using an anonymous bean to define the Recorder service seems sensible, but it seems that it prevents proper container management of the transactions.</li>
 <li>Non-JTA data sources. Both JTA and non-JTA data sources need to be defined.</li>
 <li>""nonfatal general error: org.apache.openjpa.persistence.PersistenceException: Error extracting class information from "bundleresource://43.fwk1934652240/"." This error is
 caused by forgetting the following line from the persistence.xml (also available as checkbox on the General tab):
 <p class="xml">&lt;exclude-unlisted-classes&gt;true&lt;/exclude-unlisted-classes&gt;
 <li>Forgetting to explicitly exclude unlisted classes can also cause the following runtime error:
 <p class="code">&lt;openjpa-2.0.0-r422266:935683 nonfatal general error&gt; org.apache.openjpa.persistence.PersistenceException: Error extracting class information from "bundleresource://42.fwk1060257586/".
 	at org.apache.openjpa.kernel.AbstractBrokerFactory.newBroker(AbstractBrokerFactory.java:208)
 	at org.apache.openjpa.kernel.DelegatingBrokerFactory.newBroker(DelegatingBrokerFactory.java:156)
 </p>
 <To resolve, make  the following line is in the persistence.xml (also available as checkbox on the General tab):
 <p class="xml">&lt;exclude-unlisted-classes&gt;true&lt;/exclude-unlisted-classes&gt;

 </p>
 </li>

 <li>Using the OpenJPA entity enhancement Eclipse plugin. The OpenJPA provide a plugin for Eclipse which
 automatically enhances entities, but it doesn't work very well, probably because it's
 built on OpenJPA 1.2. Add your own builder or use an ant task.</li>
 </ul>

 <p>If importing the existing projects into an Eclipse WTP/OSGi Application Tools
 installation, it's necessary to create an OpenJPA user library by navigating to <strong>Window&rarr;Preferences&rarr;Java&rarr;Build Path&rarr;User libraries</strong> and creating a new library called OpenJPA which includes the geronimo-jpa and org.apache.aries.jpa.container jars.
 </p>

 </body>
 </html>