From 1a22dfbaa23d00ae2204cb7a49077d6e76c556ee Mon Sep 17 00:00:00 2001
From: Sanjay Dalal <sanjay.dalal@berkeley.edu>
Date: Mon, 21 Dec 2009 20:09:11 +0000
Subject: [PATCH] CSPACE-514 added javadoc plugin to pom.xml (trunk and main
 levels only). complete javadoc is created (later on config for public only).
 also added doc target for build.xml (trunk and main levels). the ant target
 also jars up javadocs. the dist targets in both trunk and main now dist
 javadoc jar as well mvn javadoc:aggregate (to generate javadoc only) ant doc
 (calls javadoc:aggregate and jars up the javadoc) ant dist (now copies
 javadoc jar to dist)

M    trunk/services/common/src/main/java/org/collectionspace/services/common/security/UnauthorizedException.java
M    trunk/services/pom.xml
M    trunk/services/build.xml
M    trunk/pom.xml
M    trunk/build.xml
---
 build.xml                                     |  6 ++-
 pom.xml                                       | 54 ++++++++++++-------
 services/build.xml                            | 27 +++++++++-
 .../security/UnauthorizedException.java       |  6 +--
 services/pom.xml                              |  8 +++
 5 files changed, 75 insertions(+), 26 deletions(-)

diff --git a/build.xml b/build.xml
index e16026705..c5ff65e15 100644
--- a/build.xml
+++ b/build.xml
@@ -198,6 +198,10 @@
         </exec>
     </target>
 
+    <target name="doc" description="Build Java API docs">
+        <ant antfile="services/build.xml" target="doc" inheritAll="false"/>
+    </target>
+
     <target name="gen_ddl"
             description="generate service-specific tables(s), indices, etc.">
         <ant antfile="services/build.xml" target="gen_ddl" inheritAll="false"/>
@@ -217,7 +221,7 @@
         </sql>
         <ant antfile="services/build.xml" target="create_db" inheritAll="false"/>
     </target>
-    
+
 
     <target name="deploy" depends="install"
             description="deploy services in ${jboss.server.cspace}">
diff --git a/pom.xml b/pom.xml
index 31a485ee0..3a6fd1ed9 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <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">
-    
+
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.collectionspace.services</groupId>
     <version>1.0</version>
     <artifactId>org.collectionspace.services</artifactId>
     <packaging>pom</packaging>
     <name>services</name>
-    
+
     <properties>
         <jboss.version>4.2.3.GA</jboss.version>
         <jboss.ejb.version>3.0</jboss.ejb.version>
@@ -15,28 +15,28 @@
         <nuxeo.version.5.2>5.2.1-SNAPSHOT</nuxeo.version.5.2>
         <nuxeo.version.1.5>1.5.1-SNAPSHOT</nuxeo.version.1.5>
     </properties>
-    
+
     <distributionManagement>
         <repository>
             <id>libs-releases-local</id>
             <name>libs-releases-local</name>
             <url>http://source.collectionspace.org:8081/artifactory/libs-releases-local</url>
         </repository>
-        
+
         <snapshotRepository>
             <id>libs-snapshots-local</id>
             <name>libs-snapshots-local</name>
             <url>http://source.collectionspace.org:8081/artifactory/libs-snapshots-local</url>
         </snapshotRepository>
     </distributionManagement>
-    
+
     <modules>
         <module>3rdparty</module>
         <module>services</module>
     </modules>
-    
+
     <repositories>
-        
+
         <repository>
             <id>maven2-repository.dev.java.net</id>
             <name>Java.net Maven 2 Repository</name>
@@ -70,7 +70,7 @@
                 <enabled>true</enabled>
             </snapshots>
         </repository>
-        
+
         <repository>
             <id>maven repo</id>
             <name>maven repo</name>
@@ -96,26 +96,26 @@
                 <enabled>false</enabled>
             </snapshots>
         </repository>
-        
-        <!--        
+
+        <!--
             <repository>
             <id>maven2-repository.dev.java.net</id>
             <name>Java.net Maven 2 Repository</name>
             <url>http://download.java.net/maven/2</url>
             <snapshots>
             <enabled>false</enabled>
-            </snapshots>            
+            </snapshots>
             </repository>
-        -->        
+        -->
         <!--
             <repository>
             <id>sun</id>
             <url>http://download.java.net/maven/2</url>
             <snapshots>
             <enabled>false</enabled>
-            </snapshots>            
+            </snapshots>
             </repository>
-        -->        
+        -->
         <repository>
             <id>jboss</id>
             <url>http://repository.jboss.org/maven2</url>
@@ -141,14 +141,14 @@
         </repository>
 
     </repositories>
-    
+
     <pluginRepositories>
-        
+
         <pluginRepository>
             <id>maven2-repository.dev.java.net</id>
             <url>http://download.java.net/maven/2</url>
         </pluginRepository>
-        
+
         <pluginRepository>
             <id>maven-repository.dev.java.net</id>
             <name>Java.net Maven 1 Repository (legacy)</name>
@@ -166,7 +166,7 @@
         </pluginRepository>
 
     </pluginRepositories>
-    
+
     <build>
         <pluginManagement>
             <plugins>
@@ -197,7 +197,7 @@
                     <artifactId>maven-war-plugin</artifactId>
                     <version>2.0.1</version>
                     <configuration>
-                        
+
                         <warSourceExcludes>WEB-INF/lib/*.jar</warSourceExcludes>
                         <archive>
                             <manifest>
@@ -206,7 +206,7 @@
                         </archive>
                     </configuration>
                 </plugin>
-                
+
             </plugins>
         </pluginManagement>
     </build>
@@ -242,4 +242,18 @@
             </dependency>
         </dependencies>
     </dependencyManagement>
+
+    <reporting>
+        <plugins>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>2.6.1</version>
+                <configuration>
+                    <show>public</show>
+                </configuration>
+            </plugin>
+        </plugins>
+    </reporting>
 </project>
diff --git a/services/build.xml b/services/build.xml
index de51ae0c1..81fb91fe1 100644
--- a/services/build.xml
+++ b/services/build.xml
@@ -8,6 +8,7 @@
     <property file="${services.trunk}/build.properties" />
     <property name="mvn.opts" value="" />
     <property name="src" location="src"/>
+    <property name="javadoc.jar" value="org.collectionspace.services-javadoc.jar"/>
 
     <condition property="osfamily-unix">
         <os family="unix" />
@@ -104,6 +105,26 @@
         </exec>
     </target>
 
+    <target name="doc" depends="install,doc-unix,doc-windows" description="Build Java API docs">
+        <jar destfile="${basedir}/target/${javadoc.jar}"
+             basedir="${basedir}/target/site"
+             />
+    </target>
+    <target name="doc-unix" if="osfamily-unix">
+        <exec executable="mvn" failonerror="true">
+            <arg value="javadoc:aggregate" />
+            <arg value="${mvn.opts}" />
+        </exec>
+    </target>
+    <target name="doc-windows" if="osfamily-windows">
+        <exec executable="cmd" failonerror="true">
+            <arg value="/c" />
+            <arg value="mvn.bat" />
+            <arg value="javadoc:aggregate" />
+            <arg value="${mvn.opts}" />
+        </exec>
+    </target>
+
     <target name="gen_ddl"
             description="generate service-specific tables(s), indices, etc.">
         <ant antfile="authentication/build.xml" target="gen_ddl" inheritAll="false"/>
@@ -138,8 +159,8 @@
             description="undeploy services from ${jboss.server.cspace}">
         <ant antfile="JaxRsServiceProvider/build.xml" target="undeploy" inheritAll="false"/>
         <ant antfile="vocabulary/build.xml" target="undeploy" inheritAll="false"/>
-        <ant antfile="contact/build.xml" target="undeploy" inheritAll="false"/>        
-        <ant antfile="dimension/build.xml" target="undeploy" inheritAll="false"/>        
+        <ant antfile="contact/build.xml" target="undeploy" inheritAll="false"/>
+        <ant antfile="dimension/build.xml" target="undeploy" inheritAll="false"/>
         <ant antfile="acquisition/build.xml" target="undeploy" inheritAll="false"/>
         <ant antfile="intake/build.xml" target="undeploy" inheritAll="false"/>
         <ant antfile="collectionobject/build.xml" target="undeploy" inheritAll="false"/>
@@ -166,6 +187,8 @@
         <ant antfile="vocabulary/build.xml" target="dist" inheritAll="false"/>
         <ant antfile="acquisition/build.xml" target="dist" inheritAll="false"/>
         <ant antfile="JaxRsServiceProvider/build.xml" target="dist" inheritAll="false"/>
+        <copy file="${basedir}/target/${javadoc.jar}"
+              todir="${services.trunk}/${dist.server.cspace}/cspace/services/docs"/>
     </target>
 
     <!-- this target is called in order based on the dependencies between the services -->
diff --git a/services/common/src/main/java/org/collectionspace/services/common/security/UnauthorizedException.java b/services/common/src/main/java/org/collectionspace/services/common/security/UnauthorizedException.java
index 7c99fa36a..730a7d2cb 100644
--- a/services/common/src/main/java/org/collectionspace/services/common/security/UnauthorizedException.java
+++ b/services/common/src/main/java/org/collectionspace/services/common/security/UnauthorizedException.java
@@ -26,9 +26,9 @@ package org.collectionspace.services.common.security;
 import org.collectionspace.services.common.ServiceException;
 
 /**
- * ServiceForbidenException is thrown when access to service is not allowed for
- * one or more of the following reasons:
- * - tenant id not found
+ * UnauthorizedException is thrown when authentication to the service fails. Usually
+ * this is thrown when 2nd step of authentication to the service fails. This step
+ * includes associating the user with tenant(s) and role(s).
  * @author 
  */
 public class UnauthorizedException extends ServiceException {
diff --git a/services/pom.xml b/services/pom.xml
index ac2cedd59..4c25658c3 100644
--- a/services/pom.xml
+++ b/services/pom.xml
@@ -103,6 +103,14 @@
     </build>
     <reporting>
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>2.6.1</version>
+                <configuration>
+                    <!--show>public</show-->
+                </configuration>
+            </plugin>
             <!--plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>taglist-maven-plugin</artifactId>
-- 
2.47.3