+++ /dev/null
-The custom directory contains the information necessary to build
-extension for the Shibboleth IdP and SP at the same time they are built, and
-have these extensions bundled with their respective war file.
-
-1. Directory Structure
- custom
- /lib - this directory is where an extension and its
- libraries are placed after they are built
- /web - this directory is where an extension's web pages
- are placed after the extension is built
- extension-build.properties - this contains default properties
- needed for the extension build process
- !!! DO NOT EDIT THIS FILE !!!
- extension-build.xml - the ant build file for building extensions
- !!! DO NOT EDIT THIS FILE !!!
- README.txt - this document
-
-
-2. Using the Extension Build Process
-The extension build process depends on an extension having a specific directory
-structure, so that the extension build file knows where to find everything. The
-root directory of you extension can be named anything you with, but it must contain
-the following directories
- your-extension-directory/
- bin/ - [Optional] This directory contains any binary or script files that need to
- be installed on the filesystem in the IdP or SP home bin directory. This
- can include subdirectories. The macros $EXTENSION_NAME$ and $IDP_HOME$ or
- $SP_HOME$ will be exapanded for all files in this directory.
- etc/ - [Optional] This directory contains any configuration files that need to
- be installed on the filesystem under the IdP or SP home etc directory. This
- can include subdirectories. All files will be installed into a subdirectory
- named after the extension module. The macros $EXTENSION_NAME$ and $IDP_HOME$ or
- $SP_HOME$ will be exapanded for all files in this directory.
- lib/ - [REQUIRED if 'src' is present] any third party jars your extension needs
- src/ - [Optional] your extension's source
- src-conf/ - [Optional] This directory contains any files which are not java source
- files but still need to be included in the extension jar (and hence be
- available on the classpath). This can include subdirectories. The macros
- $EXTENSION_NAME$ and $IDP_HOME$ or $SP_HOME$ will be exapanded for all files
- in this directory.
- tests/ - [Optional] Your extension's JUnit test case source. Test case files MUST
- end with "Test.java" (i.e. the name must match *Test.java). Resources other
- than Java source files placed in this directory are added to the unit testing
- classpath (e.g. if you have "conf/foo.xml" in the tests directory it will appear
- on the classpath under /conf/foo.xml").
-
- web/ - [Optional] Any web pages, images, JSPs, etc. that should be included with the war
- build.properties - [REQUIRED] build properties for your extension
- (see below for required and optional properties)
-
-The following directories are created, and destroyed, by the extension build process and as
-such developers should never rely on them: build, dist, doc/api. Any other directory may be
-created and bundled with the extension, the build process will simply ignore them.
-
-The macro $IDP_HOME$ is only expanded during an IdP install and $SP_HOME$ is only
-expanded during an SP install.
-
-2.1 Steps for Using the Extensions Build Process
-I. Create a directory under the custom directory with the structure mentioned above. Any
-extra directories will be ignored so it is safe to bundle additional information with your
-extension such as documentation.
-
-II. Place your code and other resources in the directory structure you just set up
-
-III. Compile and deploy Shibboleth as normal.
-
-2.2 Build File Properties
- The build file supports the following properties on a per-extension basis.
- ext.name - [REQUIRED] The name of your resulting extension jar file (.jar will be appended to the name)
- gen.ext.docs - [Optional] This controls whether Java docs will be generated for your
- extension. A value of "true" will result in them being generated, any other
- value will result in them not being generated, if this property is missing
- the default value of "true" is used.
- test.ext - [Optional] This controls whether the JUnit tests for your extension are run.
- A value of "true" will result in them being run, any other value will result
- in them not being skipped, if this property is missing the default value of
- "true" is used.
-
-3. Cautionary Note
-DO NOT include libraries, with your extension, that are included with the Shibboleth
-IdP or SP. If you do, and there are version mismatches between the two jars, you will get
-unexpected exceptions during runtime as class versions conflict.
-
-4. Common Errors
-4.1 /path/to/extension/lib not found
- This error occurs because Ant is unable to ignore references to directories of jars that don't
- exist. Simply create a 'lib' directory in your extension directory structure, you do not have
- to place anything in it.
-
-4.2 Duplicate web resources
- If Ant encounters more than one web resource, like a JSP page, with the same name in the same
- destination in the war it will place N copies of that file in the war (per the zip spec), one
- for each time it encounters the file. The contents of ALL files will be the contents of the
- last file with that name that it encountered. So, if you attempt to override the login.jsp file
- in your extension, for example, your war will have two login.jsp files and both will contain the
- contents of your extension's log in jsp (because it's encountered after the main shib one).
-
+++ /dev/null
-<!--
- This file is imported in to the main Shibboleth build.xml file and
- contains all targets used for building IdP and SP extensions. These
- targets are not designed to be called by anything other than the main
- Shibboleth build file.
-
- Chad La Joie
- July 25, 2005
--->
-<project name="Shibboleth-Extensions" default="ext-invoke" basedir=".">
-
- <!-- Classpath for compiling an extension -->
- <path id="ext-compile-path">
- <!-- Shibboleth Libraries -->
- <path refid="build.path" />
-
- <!-- Extension's libraries -->
- <fileset dir="${ext.lib}">
- <include name="**/*.jar" />
- </fileset>
-
- <!-- Extension classes -->
- <pathelement location="${ext.classes}" />
- </path>
-
- <!-- Classpath for testing an extension -->
- <path id="ext-test-path">
- <!-- Extension Compilation Path -->
- <path refid="ext-compile-path" />
-
- <!-- Extension test classes -->
- <pathelement location="${ext.test.classes}" />
- </path>
-
- <!-- Loops through all the extension directories and executes a particular operation on them -->
- <target name="ext-invoke" description="Invoke operation extensions">
- <for keepgoing="true" param="module-path">
- <dirset dir="${exts.dir}">
- <include name="*" />
- <exclude name="lib" />
- <exclude name="web" />
- </dirset>
- <sequential>
- <antcall target="${ext.build.function}">
- <param name="ext.root" value="@{module-path}" />
- </antcall>
- </sequential>
- </for>
- </target>
-
- <!-- Builds a single extension -->
- <target name="ext-build" depends="ext-build-init" description="Builds the extension">
- <echo message="--- Starting to build module ${ext.name} in ${ext.root}" />
-
- <!-- Compile the source -->
- <antcall target="ext-compile" />
-
- <!-- Generate Javadocs -->
- <antcall target="ext-gen-docs" />
-
- <!-- Copy over non-source files -->
- <antcall target="ext-copy-src-conf" />
-
- <!-- Run unit tests if we're supposed to -->
- <antcall target="ext-test" />
-
- <!-- Put the libraries where the IdP and SP packaging can pick them up -->
- <antcall target="ext-copy-libs" />
-
- <!-- Put the webpages where the IdP and SP packaging can pick them up -->
- <antcall target="ext-copy-webpages" />
-
- <echo message="--- Extension ${ext.name} built" />
- </target>
-
- <target name="ext-load-properties" description="Loads property files needed by build process">
- <!-- Load extension specific properties. -->
- <if>
- <not>
- <available file="${ext.root}/build.properties" />
- </not>
- <then>
- <fail message="No build.properties file found for extension in ${ext.root}; this file is required." />
- </then>
- </if>
- <property file="${ext.root}/build.properties" />
-
- <!-- Load default properties -->
- <property file="${exts.dir}/extension-build.properties" />
-
- <fail unless="ext.name" message="The extension ${ext.root} does not contain the required (ext.name) property in its build.properties file." />
- </target>
-
- <!-- Initialize everything we need. -->
- <!-- The properties loaded here are scoped to this particular extension build -->
- <target name="ext-build-init" depends="ext-load-properties" description="Sets up everything to prepare for the build">
-
- <!-- Create needed directories -->
- <mkdir dir="${ext.dist}" />
- <mkdir dir="${ext.build}" />
- <mkdir dir="${ext.classes}" />
- <mkdir dir="${ext.test.classes}" />
- <mkdir dir="${ext.docs}" />
- </target>
-
- <!-- Compiles the extension -->
- <target name="ext-compile" description="Compiles an extension">
- <!-- Compile any source that might be out there -->
- <if>
- <available file="${ext.src}" />
- <then>
- <echo message="Compiling extension source" />
- <javac srcdir="${ext.src}"
- destdir="${ext.classes}"
- classpathref="ext-compile-path"
- includes="**/*.java"
- debug="on"
- source="1.4"
- deprecation="true"/>
- </then>
- </if>
- </target>
-
- <!-- Copies files from etc directory to dist directory to be bundled with extension jar -->
- <target name="ext-copy-src-conf" description="Copys non-source files to place where they will be added to jar">
- <!-- Copy any extra stuff that needs to be on the classpath -->
- <if>
- <available file="${ext.src.conf}" />
- <then>
- <echo message="Detected files in the extensions 'src-conf' directory, ensuring they are bundled with the extension's jar." />
- <copy todir="${ext.classes}">
- <fileset dir="${ext.src.conf}">
- <include name="**" />
- </fileset>
- </copy>
- </then>
- </if>
- </target>
-
- <!-- Move third party libraries to be picked up by the war -->
- <target name="ext-copy-libs" description="Moves third party libraries to be picked up by the war">
- <if>
- <available file="${ext.lib}" />
- <then>
- <copy todir="${exts.dir}/lib">
- <fileset dir="${ext.lib}" includes="*.jar" />
- </copy>
- </then>
- </if>
- </target>
-
- <!-- Move web resources to be picked up by the war -->
- <target name="ext-copy-webpages" description="Moves web resources to be picked up by the war">
- <if>
- <available file="${ext.webpages}" />
- <then>
- <copy todir="${exts.dir}/web">
- <fileset dir="${ext.webpages}" />
- </copy>
- </then>
- </if>
- </target>
-
-
- <!-- Run any unit tests for the extension -->
- <target name="ext-test" description="Runs extension unit test">
- <if>
- <equals arg1="${test.ext}" arg2="true" />
- <then>
- <if>
- <available file="${ext.test.src}" />
- <then>
- <echo message="Compiling extension test source" />
- <javac srcdir="${ext.test.src}"
- destdir="${ext.test.classes}"
- classpathref="ext-compile-path"
- includes="**/*.java"
- debug="on"
- source="1.4"
- deprecation="true"/>
-
- <!-- Copy any conf files over so that they end up on the classpathh -->
- <copy todir="${ext.test.classes}">
- <fileset dir="${ext.test.src}">
- <include name="**" />
- <exclude name="**/*.java"/>
- </fileset>
- </copy>
-
- <echo message="Running tests cases for extension ${ext.name}" />
- <junit printsummary="no" fork="yes" haltonerror="true" haltonfailure="true" dir="${ext.root}">
- <jvmarg value="-Djava.endorsed.dirs=${endorsed}" />
- <classpath refid="ext-test-path"/>
- <formatter type="plain" />
- <batchtest todir="${ext.root}">
- <fileset dir="${ext.test.classes}">
- <include name="**/*Test.class"/>
- </fileset>
- </batchtest>
- </junit>
- </then>
- </if>
- </then>
- </if>
- </target>
-
- <!-- Generates the Javadocs for the extension -->
- <target name="ext-gen-docs" description="Generates Javadocs for extension">
- <if>
- <equals arg1="${gen.ext.docs}" arg2="true" />
- <then>
- <if>
- <available file="${ext.src}" />
- <then>
- <echo message="Generating javadocs for extension ${ext.name}" />
- <javadoc sourcepath="${ext.src}" destdir="${ext.docs}" packagenames="*" author="true" version="true" windowtitle="${ext.name} Shibboleth Extension Java API" doctitle="${ext.name} Shibboleth Extension Java API" failonerror="false">
- <classpath refid="build.path" />
- <link href="http://java.sun.com/j2se/1.5.0/docs/api/" />
- </javadoc>
- </then>
- </if>
- </then>
- </if>
- </target>
-
- <!-- Jars up the extension -->
- <!--
- Required parameters
- exts.dir - the root directory of the extensions (contains all the individual extension directories)
- ext.filesystem.home - the path on the filesystem that the extension will be installed
- expected subdirectories are 'bin, 'etc', and 'lib'
- ext.home.token - the token, in config files, to replace with the path to the IdP/SP home
- -->
- <target name="ext-package" depends="ext-load-properties" description="Packages up the extension">
- <if>
- <available file="${ext.classes}" />
- <then>
- <replace dir="${ext.classes}" token="${ext.home.token}" value="${ext.filesystem.home}" excludes="*.class" />
- <replace dir="${ext.classes}" token="$EXTENSION_NAME$" value="${ext.name}" excludes="*.class" />
- <jar jarfile="${ext.dist}/${ext.name}.jar" basedir="${ext.classes}" update="false" />
- <copy file="${ext.dist}/${ext.name}.jar" todir="${exts.dir}/lib" />
- <delete dir="${ext.classes}" />
- </then>
- </if>
- </target>
-
- <!-- Install extension files (configuration, scripts, etc) on to the filesystem -->
- <!--
- Required Paramter
- ext.filesystem.home - the path on the filesystem that the extension will be installed
- expected subdirectories are 'bin, 'etc', and 'lib'
- ext.home.token - the token that represents the extensions installation point within
- the various configuration files (those in the extensions 'etc' and 'src-conf' directories)
- -->
- <target name="ext-install-filesystem" depends="ext-build-init" description="Installs extension files on to the filesystem">
- <echo message="Installing extension ${ext.name} to ${ext.filesystem.home}" />
-
- <!-- Copy anything in the etc directory to the extension's installation point etc directory -->
- <if>
- <available file="${ext.etc}" />
- <then>
- <if>
- <available file="${ext.filesystem.home}/etc/${ext.name}" />
- <then>
- <echo>--------------------------------------------------------------------------------------</echo>
- <echo>---</echo>
- <echo>--- NOTE: Existing Shibboleth extension module configuration at ${line.separator}--- ${ext.filesystem.home}/etc/${ext.name} will not be overwritten.</echo>
- <echo>---</echo>
- <echo>--------------------------------------------------------------------------------------</echo>
- </then>
- <else>
- <mkdir dir="${ext.filesystem.home}/etc/${ext.name}" />
- <copy todir="${ext.filesystem.home}/etc/${ext.name}">
- <fileset dir="${ext.etc}">
- <include name="**" />
- </fileset>
- </copy>
- <replace dir="${ext.filesystem.home}/etc/${ext.name}" token="${ext.home.token}" value="${ext.filesystem.home}" />
- <replace dir="${ext.filesystem.home}/etc/${ext.name}" token="$EXTENSION_NAME$" value="${ext.name}" />
- </else>
- </if>
- </then>
- </if>
-
- <!-- Copy anything in the bin directory to the extension's installation point bin directory -->
- <if>
- <available file="${ext.bin}" />
- <then>
- <copy todir="${ext.filesystem.home}/bin">
- <fileset dir="${ext.bin}">
- <include name="**" />
- </fileset>
- </copy>
- <replace dir="${ext.filesystem.home}/bin" token="${ext.home.token}" value="${ext.filesystem.home}" />
- <replace dir="${ext.filesystem.home}/bin" token="$EXTENSION_NAME$" value="${ext.name}" />
- <chmod dir="${ext.filesystem.home}/bin" perm="ug+rx" includes="**/*" />
- </then>
- </if>
-
- <!-- Copy anything in the lib directory to the extension's installation point lib directory -->
- <if>
- <available file="${ext.lib}" />
- <then>
- <copy todir="${ext.filesystem.home}/lib">
- <fileset dir="${ext.lib}">
- <include name="*" />
- </fileset>
- </copy>
- </then>
- </if>
-
- <!-- Copy the extension jar to the extension's installation point lib directory -->
- <if>
- <available file="${ext.dist}/${ext.name}.jar" />
- <then>
- <copy file="${ext.dist}/${ext.name}.jar" todir="${ext.filesystem.home}/lib" />
- </then>
- </if>
- </target>
-
- <!-- Cleans up classes files -->
- <target name="ext-clean-build" depends="ext-load-properties" description="Cleans up any build created resources">
- <delete dir="${ext.build}" failonerror="false" />
- </target>
-
- <!-- Cleans up java docs -->
- <target name="ext-clean-javadocs" depends="ext-load-properties" description="Deletes generated javadocs">
- <delete dir="${ext.docs}" failonerror="false" />
- </target>
-
- <!-- Cleans up distribution files -->
- <target name="ext-clean-dist" depends="ext-load-properties" description="Deletes distribution generated files">
- <delete dir="${ext.dist}" failonerror="false" />
- </target>
-</project>
projects / java-idp.git / commitdiff