incubator-isis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From danhayw...@apache.org
Subject svn commit: r1139826 - /incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
Date Sun, 26 Jun 2011 16:07:32 GMT
Author: danhaywood
Date: Sun Jun 26 16:07:32 2011
New Revision: 1139826

URL: http://svn.apache.org/viewvc?rev=1139826&view=rev
Log:
updates to the contributors guide

Modified:
    incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml

Modified: incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml?rev=1139826&r1=1139825&r2=1139826&view=diff
==============================================================================
--- incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml (original)
+++ incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml Sun Jun 26 16:07:32
2011
@@ -5520,7 +5520,7 @@ gpg --armor --export nnnnnnnn >>KE
         key. The process for this is described <ulink
         url="http://www.apache.org/dev/release-signing.html#key-signing-party">here</ulink>
         and <ulink
-        url="http://wiki.apache.org/apachecon/PgpKeySigning">here</ulink>.d</para>
+        url="http://wiki.apache.org/apachecon/PgpKeySigning">here</ulink>.</para>
       </sect1>
     </appendix>
 
@@ -5540,13 +5540,355 @@ gpg --armor --export nnnnnnnn &gt;&gt;KE
         correctly</title>
 
         <para>The quickstart archetype is created by "reverse-engineering" the
-        quickstart prototype application
-        <package>[oai.support:quickstart]</package>. Therefore a prerequisite
-        is to ensure that this application works correctly.</para>
+        quickstart prototype application that resides in
+        <filename>trunk/framework/examples/quickstart</filename>. Therefore a
+        prerequisite is to ensure that this application works
+        correctly.</para>
 
-        <para>See the <ulink
-        url="https://cwiki.apache.org/confluence/display/ISIS/RecreatingMavenArchetypeFromProject">wiki</ulink>
-        for further details.</para>
+        <sect2>
+          <title>Prerequisites</title>
+
+          <para>Eclipse configuration</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>recommend use JEE edition (rather than standard Java
+              edition) with its WTP (web tools) tooling</para>
+
+              <para>This will allow you to test the Run As...&gt; Run On
+              Server functionality</para>
+            </listitem>
+
+            <listitem>
+              <para>in addition, m2eclipse must be installed (for ease of
+              installing, but also because the .launch files that are used
+              also depend on the m2eclipse classpath provider entry)</para>
+
+              <para>Notes:</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para><ulink
+                  url="http://m2eclipse.sonatype.org/sites/m2e">m2eclipse</ulink>
+                  is now bundled as part of Eclipse 3.7 (indigo)</para>
+                </listitem>
+
+                <listitem>
+                  <para>using earlier distributions you may find that you need
+                  to manually install <ulink
+                  url="http://download.eclipse.org/tools/gef/updates/releases/">Zest</ulink>
+                  first. </para>
+
+                  <para>See this <ulink
+                  url="http://domengrabec.wordpress.com/2010/12/14/installing-maven-on-eclipse/">blog
+                  post</ulink> for an explanation as to why</para>
+                </listitem>
+
+                <listitem>
+                  <para>install m2eclipse from its update site </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+
+          <para>Tomcat (JEE) install:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>Tomcat (7)</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para>install server (download from <ulink
+                  url="http://tomcat.apache.org/download-70.cgi">here</ulink>)</para>
+                </listitem>
+
+                <listitem>
+                  <para>configure server</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+
+          <para>Groovy is also used in this process and is a
+          prerequisite<itemizedlist>
+              <listitem>
+                <para>1.7.6 was used, but earlier versions are very likely to
+                be ok</para>
+              </listitem>
+
+              <listitem>
+                <para>add 'groovy' to $PATH</para>
+              </listitem>
+            </itemizedlist></para>
+
+          <para></para>
+        </sect2>
+
+        <sect2>
+          <title>Import the Quickstart Project</title>
+
+          <para>The quickstart app include Eclipse launch configurations (eg
+          <filename>quickstart/quickrun/ide/eclipse/launch/*.launch</filename>.
+          These files have a hard-coded reference to the project file itself,
+          which means that for them to work, the app that will be generated by
+          the eventual quickstart archetype should be imported "in the right
+          way".</para>
+
+          <para>To minimize the chance of confusion by users who may not know
+          every obscure feature of Eclipse, the quickstart prototype app is
+          therefore written in such a way that the app should be imported
+          using the defaults in the 'Import Maven projects' dialogue. </para>
+
+          <note>
+            <para>This is different from the way that we import the rest of
+            the <emphasis>Isis</emphasis> framework (where we use
+            Advanced&gt;Name Template=\[groupId]:\[artifactId].</para>
+          </note>
+
+          <para>Therefore, import quickstart prototype app:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>File&gt;Import&gt;Maven&gt;Existing Maven Projects</para>
+            </listitem>
+
+            <listitem>
+              <para>Root Directory=trunk/examples/quickstart</para>
+            </listitem>
+
+            <listitem>
+              <para>Refresh</para>
+            </listitem>
+
+            <listitem>
+              <para>Finish</para>
+            </listitem>
+          </itemizedlist>
+
+          <para>Then, verify that the prototype app works as expected. Full
+          details are [at the bottom of this page|#testing]</para>
+        </sect2>
+
+        <sect2>
+          <title>Testing</title>
+
+          <para>These steps are to test both the prototype app (used to
+          generate the archetype) and also the resultant app (from the
+          generated archetype, prior to commit).</para>
+
+          <note>
+            <para>If you are going to use Maven to run these tests as
+            explained below, you need to build the quickstart project. To do
+            that, go to the directory where quickstart project's POM file is
+            located (trunk/examples/quickstart) and then run <code>mvn clean
+            install</code>.</para>
+          </note>
+
+          <para></para>
+
+          <para>*** to tidy up; the raw information is here, however.</para>
+
+          <para></para>
+
+          <sect3>
+            <title>Build from the mvn command line</title>
+
+            <para></para>
+
+            <programlisting>* quickstart/
+** mvn clean install</programlisting>
+
+            <para></para>
+
+            <para>This also runs tests.</para>
+
+            <para>*** describe how to view results of tests.</para>
+
+            <para></para>
+          </sect3>
+
+          <sect3>
+            <title>Run shaded JARs from mvn command line</title>
+
+            <para></para>
+
+            <programlisting>
+* quickstart/quickrun
+** mvn antrun:run -D exec=dnd
+** mvn antrun:run -D exec=html
+** mvn antrun:run -D exec=xhtml
+** mvn antrun:run -D exec=json</programlisting>
+
+            <para></para>
+
+            <para></para>
+          </sect3>
+
+          <sect3>
+            <title>Quickrun .launch configurations</title>
+
+            <para></para>
+
+            <programlisting>
+** quickrun/
+*** ide/eclipse/launch/quickstart-quickrun-dnd.launch, Run As &gt; ...
+*** ide/eclipse/launch/quickstart-quickrun-html.launch, Run As &gt; ...
+**** browse to http://localhost:8080/logon.app
+***** ideally should be just "/", but haven't figured out a way to make this work yet
+*** ide/eclipse/launch/quickstart_quickrun_json.launch, Run As &gt; ...
+**** browse to http://localhost:8080
+*** ide/eclipse/launch/quickstart_quickrun_xhtml.launch, Run As &gt; ...
+**** browse to http://localhost:8080
+
+
+</programlisting>
+
+            <para></para>
+          </sect3>
+
+          <sect3>
+            <title>Run using web.xml</title>
+
+            <para>Three approaches, all of which are equivalent:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>mvn jetty:run</para>
+              </listitem>
+
+              <listitem>
+                <para>using Eclipse .launch configurations</para>
+
+                <para>NB: this is different from the .launch in quickrun,
+                because it uses <code>org.apache.isis.WebServer</code> class
+                (hence <filename>web.xml</filename>) rather than
+                <code>org.apache.isis.Isis</code> command line class.</para>
+              </listitem>
+
+              <listitem>
+                <para>using Eclipse WTP support ("Run as&gt; Run on
+                server")</para>
+              </listitem>
+            </itemizedlist>
+
+            <para></para>
+
+            <para>To test using <code>mvn jetty:run</code>:</para>
+
+            <programlisting>
+
+** quickstart-viewer-html/
+*** mvn jetty:run
+*** browse to http://localhost:8080/quickstart-viewer-html/
+** quickstart-viewer-xhtml/
+*** mvn jetty:run
+** quickstart-viewer-json/
+*** mvn jetty:run
+*** browse to http://localhost:8080/quickstart-viewer-restful/
+** quickstart-viewer-scimpi/
+*** mvn jetty:run
+*** browse to http://localhost:8080/quickstart-viewer-scimpi/
+** quickstart-viewer-wicket/
+*** mvn jetty:run
+*** browse to http://localhost:8080/quickstart-viewer-wicket/
+</programlisting>
+
+            <para></para>
+
+            <para>To test using the Eclipse .launch file:</para>
+
+            <programlisting>
+** quickstart-viewer-html/
+*** ide/eclipse/launch/quickstart-viewer-html.launch, Run As &gt; ...
+*** browse to http://localhost:8080/logon.app
+** quickstart-viewer-xhtml/
+*** ide/eclipse/launch/quickstart-viewer-xhtml.launch, Run As &gt; ...
+*** browse to http://localhost:8080/
+** quickstart-viewer-json/
+*** ide/eclipse/launch/quickstart-viewer-json.launch, Run As &gt; ...
+*** browse to http://localhost:8080/
+** quickstart-viewer-scimpi/
+*** ide/eclipse/launch/quickstart-viewer-scimpi.launch, Run As &gt; ...
+*** browse to http://localhost:8080/
+** quickstart-viewer-wicket/
+*** ide/eclipse/launch/quickstart-viewer-wicket.launch, Run As &gt; ...
+*** browse to http://localhost:8080/</programlisting>
+
+            <para></para>
+
+            <para></para>
+
+            <para>If using Eclipse JEE edition, then you can also use "Run as
+            &gt; Run on server" to test the webapps. The prerequisite for this
+            is to configure a Server, eg Tomcat 7.0. Use
+            Windows&gt;Preferences&gt;Server&gt;Runtime
+            Environments&gt;Add</para>
+
+            <para>Then navigate to each of the web modules, and run using Run
+            &gt; Run As:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>quickstart-viewer-html/</para>
+
+                <para>browse to
+                http://localhost:8080/quickstart-viewer-html/</para>
+              </listitem>
+
+              <listitem>
+                <para>quickstart-viewer-json/</para>
+
+                <para>browse to
+                http://localhost:8080/quickstart-viewer-json/</para>
+              </listitem>
+
+              <listitem>
+                <para>quickstart-viewer-scimpi/</para>
+
+                <para>browse to
+                http://localhost:8080/quickstart-viewer-scimpi/</para>
+              </listitem>
+
+              <listitem>
+                <para>quickstart-viewer-wicket/</para>
+
+                <para>browse to
+                http://localhost:8080/quickstart-viewer-wicket/</para>
+              </listitem>
+
+              <listitem>
+                <para>quickstart-viewer-xhtml/</para>
+
+                <para>browse to
+                http://localhost:8080/quickstart-viewer-xhtml/</para>
+              </listitem>
+            </itemizedlist>
+
+            <para><note>
+                <para>It isn't possible (at least, at the time of writing
+                this) to deploy multiple WARs at the same time - they will
+                clash with JMXBean singleton failures:</para>
+              </note></para>
+          </sect3>
+
+          <sect3>
+            <title>Run tests from within IDE</title>
+
+            <para></para>
+
+            <programlisting>
+** quickstart-tests-bdd/
+*** Run as &gt; Junit Tests
+** quickstart-tests-junit/
+*** Run as &gt; Junit Tests
+
+
+</programlisting>
+
+            <para></para>
+          </sect3>
+        </sect2>
       </sect1>
 
       <sect1>



Mime
View raw message