Author: pete.muir(a)jboss.org Date: 2009-07-24 10:13:27 -0400 (Fri, 24 Jul 2009) New Revision: 3195 Modified: tck/trunk/doc/reference/en-US/installation.xml Log: Remove a lot of JBoss / Web Beans specific info, it's not really relevant Modified: tck/trunk/doc/reference/en-US/installation.xml =================================================================== --- tck/trunk/doc/reference/en-US/installation.xml 2009-07-24 13:43:07 UTC (rev 3194) +++ tck/trunk/doc/reference/en-US/installation.xml 2009-07-24 14:13:27 UTC (rev 3195) @@ -4,62 +4,63 @@ <title>Installation</title> <para> This chapter explains how to obtain the TCK and supporting software and - provides - recommendations for how to install/extract it on your system. + provides recommendations for how to install/extract it on your system. </para> <section> <title>Obtaining the Software</title> <para> - You can obtain the JSR-299 TCK project from the - <ulink url="http://anonsvn.jboss.org/repos/webbeans/tck/trunk">JBoss SVN repository</ulink> - or you can download a release from the + You can obtain a release of the CDI TCK project from the from the <ulink url="http://seamframework.org/Download">download page</ulink> on Seam Framework website. The JSR-299 TCK is distributed as a ZIP - file, which contains a multi-module Maven 2 project, the test suite, - the test suite descriptor, the audit document and documentation. At the - time of writing there is no official release of the JSR-299 TCK - available, so you need to check out the TCK from the JBoss SVN - repository. + file, which contains the TCK artifacts (the test suite binary and + source, porting package API binary and source, the test suite + descriptor, the audit source and report) in + <code>/artifacts</code> + , the TCK library dependencies in + <code>/lib</code> + and documentation in + <code>/lib</code> + . </para> - <para>The TCK project downloads additional required libraries from the - JBoss Maven 2 repository automatically, including the JBoss Test - Harness and the JSR-299 API. You may follow this approach when - assembling a TCK runner for your JSR-299 implementation.</para> <para> - The JSR-299: Contexts and Dependency Injection for Java EE 1.0 - reference implementation (RI) is Web Beans. You can obtain the latest - Web Beans release from the - <ulink url="http://seamframework.org/Download">download page</ulink> - on Seam Framework website. Web Beans includes a TCK runner that - executes the TCK on the JSR-299 RI by deploying the test artifacts to - JBoss AS 5.1. + You can also download the currnet source code from + <ulink url="http://anonsvn.jboss.org/repos/webbeans/tck/trunk">JBoss SVN repository</ulink> + . </para> - <note> - <para> - The JSR-299 RI (Web Beans) is not required for running the - JSR-299 TCK, but it can be useful as a reference for familiarizing - yourself with the TCK before testing your own JSR-299 - implementation. - </para> - </note> <para> + The TCK project is available in the JBoss Maven 2 repository as + <code>org.jboss.jsr299.tck:jsr299-tck-impl</code> + ; the POM defines all dependencies required to run the TCK. + </para> + <para> Executing the TCK requires a Java EE 5 or better runtime environment (i.e., application server), to which the test artifacts are deployed and invoked. The TCK does not depend on any particular Java EE - implementation, only that it is compliant. However, if you decide to - use JBoss AS 5.1 as the target container, you can use the JBoss AS 5.1 - connector provided with the JBoss Test Harness, alleviating the - requirement of implementing the - <literal>org.jboss.jsr299.tck.spi.Containers</literal> - SPI from the TCK porting package. You can download JBoss AS 5.1 from + implementation. + </para> + <para> + The JSR-299: Contexts and Dependency Injection for Java EE 1.0 + reference implementation (RI) project is named Web Beans. You can + obtain the latest Web Beans release from the + <ulink url="http://seamframework.org/Download">download page</ulink> + on Seam Framework website. Web Beans includes a TCK runner that + executes the TCK using Web Beans as the CDI implementation and JBoss AS + as the Java EE runtime. You can download JBoss AS 5.1 from the JBoss AS <ulink url="http://jboss.org/jbossas/downloads">project page</ulink> . </para> + <note> + <para> + Web Beans is not required for running the CDI TCK, but it can be + used as a reference for familiarizing yourself with the TCK before + testing your own CDI implementation. + </para> + </note> <para> Naturally, to execute Java programs, you must have a Java SE runtime - environment. The TCK requires Java SE 1.5 or better, which you can - obtain from the + environment. The TCK requires Java 5 or better, which you can obtain + from the <ulink url="http://java.sun.com">Java Software</ulink> website. </para> @@ -70,17 +71,17 @@ <para> Installing Java software is a bit of a misnomer. The only software - you have to - &quot;install&quot; are the runtime environments. The - remaining software - is merely extracted in a workspace directory of your + you have to &quot;install&quot; are the runtime environments. The + remaining software is merely extracted in a workspace directory of your choice. - </para> - <para>The TCK requires the following two Java runtime environments:</para> + </para> + <para> + The TCK requires the following two Java runtime environments: + </para> <itemizedlist> <listitem> <para> - Java SE 5.0 or better + Java 5 or better </para> </listitem> <listitem> @@ -90,74 +91,55 @@ </listitem> </itemizedlist> <para> - You can download Java SE from the - <ulink url="http://java.sun.com/products">Java Software</ulink> - web site. - Refer to the instructions that accompany - the software for how - to install it on your system. - You should be sure that the - <literal>JAVA_HOME</literal> - environment variable is assigned to the location of the Java SE - software before you consider the installation complete. + You should refer to vendor instructions for how to install the + runtime. </para> + <tip> + <para> + If you are using JBoss AS, it's recommended that you set the + <literal>JBOSS_HOME</literal> + environment variable to the location of the JBoss AS software. + </para> + </tip> <para> - Which Java EE runtime environment to use is your choice. Keep in - mind, though, that you must provide a custom connector if the - application server you are using is not supported by the JBoss Test - Harness. At the time of writing, JBoss AS 5.1 is the only supported - application server (table showing supported versions?) and is therefore - the recommend Java EE runtime environment. + The rest of the TCK software can simply be extracted. It's + recommended that you create a folder named jsr299 to hold all of the + jsr299-related projects. Then, extract the TCK distribution into a + subfolder named tck. If you have downloaded the Web Beans distribution, + extract it into a sibling folder named webbeans. The resulting folder + structure is shown here: </para> - <para> - JBoss - AS 5.1 can be downloaded from the JBoss AS project page. Refer to - the - instructions that accompany the software to learn how to install it - on - your system. Although not required, it&apos;s recommended that you - set - the - <literal>JBOSS_HOME</literal> - environment variable to the location of the JBoss AS software. - </para> - <para> - The rest of the TCK software can simply be extracted. It&apos;s - recommended that - you create a folder named jsr299 to hold all of the - jsr299-related - projects. Then, extract the TCK distribution into a - subfolder named tck. - If you have downloaded the Web Beans distribution, - extract it into a - sibling folder named webbeans. The resulting folder - structure is shown - here: - </para> <programlisting>jsr299/ webbeans/ tck/</programlisting> - <para> - This arrangement becomes important later on when executing tests in - Eclipse. - </para> - <section> - <title>Web Beans deployer</title> + <tip> <para> - When the TCK test suite is run (using in-container mode), it - expects to test the JSR-299 implementation provided by the - application server. Therefore, you need to install the JSR-299 - implementation in the application server. + This layout is assumed through all descriptions in this reference + guide. </para> + </tip> + + <tip> <para> - The JSR-299 RI (Web Beans) includes a JBoss AS integration - project that installs a special deployer on JBoss AS 5.x that - activates the JSR-299 RI per application when the application is - deployed. The Web Beans deployer is installed in JBoss AS 5.x from - the jboss-as directory in the Web Beans distribution. + Web Beans is built as a modular library, and as such can be + retro-fitted to Java EE 5 products as required. Red Hat Middleware + LLC bundles Web Beans in it's JBoss AS 5.1 and above releases. JBoss + AS 5.1 also allows you to upgrade the Web Beans module to the + current release (though some functionality may be disabled). This + allows you to run the CDI TCK in JBoss 5.1. </para> <para> - To install the web beans deployer, first make sure the + CDI is an integral part of Java EE 6 and above, and as such Java + EE 6 runtimes are expected to bundle a CDI implementation. + </para> + <para> + To perform the upgrade to JBoss AS 5.1: + </para> + <para> + Change to the webbeans directory. + </para> + <para> + Make sure the <literal>jboss.home</literal> property in the local.build.properties file in the jboss-as directory references a JBoss AS 5.1 installation: @@ -173,68 +155,21 @@ repository on demand. The versions of the libraries fetched are defined in the build.properties files in that directory. </para> - </section> - <section> - <title>Maven 2 and Maven 2 artifacts</title> + </tip> + <tip> <para> - As - mentioned earlier, because the JSR-299 RI and TCK are built with - Maven 2, it&apos;s essential to have Maven 2 installed on the - system. You can find documention on how to install Maven 2 in the + If decide to use Maven 2 to execute the tests (as Web Beans does + with JBoss AS), you need to install Maven You can documention on how + to install Maven 2 in the <ulink url="http://www.sonatype.com/books/maven-book/reference/installation...: The Definitive Guide</ulink> - book published by Sonatype. It merely entails extracting the - distribution and putting the bin directory in the user&apos;s PATH - environment variable. + book published by Sonatype. </para> - <programlisting>export PATH=&quot;&lt;maven2_install_dir&gt;/bin:$PATH&quot;</programlisting> - <para> - The TCK runner, introduced in section 4.2, is organized as a Maven 2 - project (herein referred to as a Maven project). Therefore, it expects - to retrieve all dependent artifacts (JAR files) from the local Maven - repository. If the artifact is missing from the local repository, it - will be fetched remotely from the JBoss Maven repository and cached in - the local repository. - </para> - <para> - One option for executing the TCK the first time is to allow Maven fetch - all required dependencies. If you want to use your own implementation - of the TCK porting package, or if you are running the TCK against your - own JSR-299 implementation, you need to install the corresponding - artifacts into your local Maven repository, at the very least. If you - don&apos;t want to use Maven at all, you&apos;ll need to implement a - project the executes the TCK runner from scratch. This guide assumes - the use of the Maven project structure. - </para> - <para> - If your JSR-299 implementation uses a Maven project structure, you can - have Maven install the artifact into your local Maven repository in the - normal way: - </para> - <programlisting>mvn install</programlisting> - <para> - If you are not using a Maven project structure, you can install each - artifact into your local Maven respository using the install goal: - </para> - <programlisting>mvn install:install-file \ --Dfile=jsr299-impl.jar \ --DgroupId=com.company.jsr299 \ --DartifactId=jsf299-impl \ --Dversion=1.0 \ --Dpackaging=jar</programlisting> - <para> - You can use this command template for installing any JAR file you need - into your local Maven respository. - </para> - <note> - <para> - The JSR-299 implementation doesn&apos;t have to be on the classpath - of the TCK runner when executing the TCK in in-container mode. The - JSR-299 implemention is expected to be provided by a compliant Java - EE container. However, the implementation does have to be on the - classpath when executing the test suite in standalone mode. + <para> + Maven will retrieve all TCK and Web Beans dependencies from the + JBoss Maven repository. </para> - </note> + </tip> </section> <section> <title>Eclipse plugins</title> @@ -256,10 +191,10 @@ <ulink url="http://testng.org/doc/eclipse.html">Eclipse page</ulink>. </para> <para> - Another essential plugin is m2eclipse. Both the TCK project and the + Another useful plugin is m2eclipse. Both the TCK project and the TCK runner project (at least the one that ships with the JSR-299 RI) are built with Maven 2. Therefore, to work with these projects in - Eclipse, you need to have support for Maven 2 project, which the + Eclipse, you may wish to have support for Maven 2 project, which the m2eclipse plugin provides. Instructions for using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the company that maintains the m2eclipse @@ -267,6 +202,5 @@ <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">... guide</ulink> dedicated to the plugin on their website. </para> - </section> - </section> + </section> </chapter>