README.maven2

JSAMP builds using maven 1.  I attempted a maven 2 conversion 
(with considerable help from Paul Harrison), but I couldn't 
get it working as well as the maven 1 build.  Problems included:

   - I couldn't get the xdoc documents to include automatically generated
     documentation fragments, because entity inclusion doesn't seem to
     work (see http://jira.codehaus.org/browse/DOXIA-250)

   - The build took much longer than it used to (Paul believes this is
     down to the dependencies report checking on repositories which time
     out, could be avoided by running mvn -o).

   - Ant file generation doesn't work which means it's hard for third
     parties to do the build from the source distribution (see http://jira.codehaus.org/browse/MANT-52).

Additionally, JSAMP has very few dependencies and so doesn't really 
benefit from Maven 2's improved dependency management.

Apart from that the build did actually work.

The changes are recorded here, in case another attempt at mvn2ising
JSAMP is made (this might well be worth it at the next release of maven 2 if the fixes to the bugs above are made).  Changes are:

  - New file pom.xml included at top level (text below)

  - Replace src/site/xdoc/navigation.xml with src/site/site.xml (text below)

  - New file src/resources/org/astrogrid/samp/jsamp.version - one line
    file containing the text "${pom.version}".

  - Some changes in file src/site/xdoc/commands.xml; entity locations
    changed from "../../../target/docs/org.astrogrid.samp.foo"
              to       "${builddocdir}/org.astrogrid.samp.foo"
    However, this didn't actually work, as noted above.  If the Doxia
    fix is ever made to maven, it might to though.

Mark Taylor 7 July 2009.

Text of files required for maven 2 build:

========================================================================
pom.xml
========================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <artifactId>jsamp</artifactId>
  <version>0.3-1</version>
  <name>JSAMP</name>
  <parent>
      <artifactId>astrogrid-base</artifactId>
      <groupId>org.astrogrid</groupId>
      <version>2009.1-SNAPSHOT</version>
  </parent>
  <description>Various components used for developing and deploying
    Simple Applications Messaging Protocol-compliant 
    applications and middleware.</description>
  <inceptionYear>2008</inceptionYear>
   <developers>
    <developer>
      <id>mbt</id>
      <name>Mark Taylor</name>
      <email>m.b.taylor@bristol.ac.uk</email>
      <url>http://www.star.bristol.ac.uk/~mbt/</url>
      <organization>Bristol University</organization>
    </developer>
  </developers>

  <properties>
    <builddocdir>${project.build.directory}/docs</builddocdir>
  </properties>

  <build>
    <sourceDirectory>src/java</sourceDirectory>
    <testSourceDirectory>src/test/java</testSourceDirectory>
    <resources>
      <resource>
        <directory>src/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>

    <plugins>

      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <argLine>-ea</argLine>
          <testFailureIgnore>true</testFailureIgnore>
          <useFile>false;</useFile>
          <includes>
            <include>org/astrogrid/samp/**/*Test.java</include>
          </includes>
        </configuration>
      </plugin>

      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.4</source>
          <target>1.4</target>
        </configuration>
      </plugin>

      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <archive>
            <manifest>
              <mainClass>org.astrogrid.samp.JSamp</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>

      <!-- Write command usage for command-line tools to files. -->
      <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <phase>pre-site</phase>
            <configuration>
              <tasks>
                <taskdef resource="net/sf/antcontrib/antlib.xml"
                         classpathref="maven.plugin.classpath"/>
                <mkdir dir="${project.build.directory}/docs"/>
                <echo>Generating command usage strings</echo>
                <for param="command" trim="true"
                     list="org.astrogrid.samp.JSamp,
                           org.astrogrid.samp.xmlrpc.HubRunner,
                           org.astrogrid.samp.gui.HubMonitor,
                           org.astrogrid.samp.test.Snooper,
                           org.astrogrid.samp.test.CalcStorm,
                           org.astrogrid.samp.test.HubTester">
                  <sequential>
                    <echo>   @{command}</echo>
                    <java classname="@{command}"
                          output="${project.build.directory}/docs/@{command}.usage"
                          fork="true" failonerror="true" logerror="true">
                      <classpath>
                        <pathelement
                             location="${project.build.outputDirectory}"/>
                      </classpath>
                      <arg value="-help"/>
                    </java>
                    <replace file="${project.build.directory}/docs/@{command}.usage">
                      <replaceFilter token="&amp;" value="&amp;amp;"/>
                      <replaceFilter token="&lt;" value="&amp;lt;"/>
                      <replaceFilter token="&gt;" value="&amp;gt;"/>
                    </replace>
                  </sequential>
                </for>
              </tasks>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>ant</groupId>
            <artifactId>ant</artifactId>
            <version>1.6.5</version>
          </dependency>
          <dependency>
            <groupId>ant-contrib</groupId>
            <artifactId>ant-contrib</artifactId>
            <version>1.0b2</version>
          </dependency>
        </dependencies>
      </plugin>

    </plugins>
  </build>
    
  <reporting>
    <plugins>
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          <links>
            <link>http://java.sun.com/j2se/1.4.2/docs/api/</link>
            <link>http://ws.apache.org/xmlrpc/xmlrpc2/apidocs/</link>
          </links> 
          <offlineLinks>
            <offlineLink>
              <url>http://java.sun.com/j2se/1.4.2/docs/api/</url>
              <location>${project.build.sourceDirectory}/../docs/packagelists/j2se</location>
            </offlineLink>
            <offlineLink>
              <url>http://ws.apache.org/xmlrpc/xmlrpc2/apidocs/</url>
              <location>${project.build.sourceDirectory}/../docs/packagelists/xmlrpc</location>
            </offlineLink>
          </offlineLinks>
          <source>1.4</source>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

  <dependencies>
    <dependency>
      <groupId>xmlrpc</groupId>
      <artifactId>xmlrpc</artifactId>
      <version>1.2-b1</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8</version>
    </dependency>
  </dependencies>
     <url>${astrogrid_doc_URL_root}/p/samp/${project.version}/</url> 
   <distributionManagement>
    <site>
      <id>agsite</id>   <!-- this is the desired layout of the site and - will have to be repeated in the  projects unfortunately until fixes to http://jira.codehaus.org/browse/MNG-2915 are available  -->
      <name>Default Site</name>
      <url>${astrogrid_doc_server_root}/p/samp/${project.version}/</url>
      <!-- terror.star.le.ac.uk/ -->
    </site>
 </distributionManagement>
  
 </project>


========================================================================
src/site/site.xml
========================================================================
<?xml version="1.0"?>
<project name="SAMP"  xmlns="http://maven.apache.org/DECORATION/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
   

  <body>
    <links>
      <item name="SAMP Information"
            href="http://www.ivoa.net/samp/"/>
      <item name="SAMP Standard"
            href="http://www.ivoa.net/Documents/latest/SAMP.html"/>
    </links>

    <menu name="Documentation">
      <item name="Introduction" href="index.html"/>
      <item name="Command-line tools" href="commands.html"/>
      <item name="API Overview" href="api.html"/>
      <item name="GUI Features" href="gui.html"/>
      <item name="Deployment" href="deployment.html"/>
      <item name="Javadocs" href="apidocs/index.html"/>
      <item name="Downloads" href="downloads.html"/>
      <item name="Change Log" href="history.html"/>
      <item name="Project Info" href="project-info.html"/>
    </menu>
  </body>
</project>