------------------------------------------------------------------------------
README file for Open Web Single Sign-On
------------------------------------------------------------------------------
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved

The contents of this file are subject to the terms
of the Common Development and Distribution License
(the License). You may not use this file except in
compliance with the License.

You can obtain a copy of the License at
https://opensso.dev.java.net/public/CDDLv1.0.html or
opensso/legal/CDDLv1.0.txt
See the License for the specific language governing
permission and limitations under the License.

When distributing Covered Code, include this CDDL
Header Notice in each file and include the License file
at opensso/legal/CDDLv1.0.txt.
If applicable, add the following below the CDDL Header,
with the fields enclosed by brackets [] replaced by
your own identifying information:
"Portions Copyrighted [year] [name of copyright owner]"

$Id: README,v 1.31 2009/11/23 21:37:02 huacui Exp $

------------------------------------------------------------------------------

%% Contents:

%% 1. Build requirements

%% 2. Library dependencies
%% 2.1 Obtaining j2ee.jar and mail.jar
%% 2.2 Obtaining shared library jars: jaxb-api.jar, jaxb-impl.jar,
jaxb-libs.jar, jaxb-xjc.jar, jaxrpc-impl.jar, jaxrpc-spi.jar,
jaxrpc-api.jar, activation.jar, saaj-api.jar, saaj-impl.jar,
relaxngDatatype.jar, xmlsec.jar, xalan.jar, xsdlib.jar,
FastInfoset.jar, jsr173_api.jar, webservices-api.jar,
webservices-rt.jar, webservices-tools.jar,
webservices-extra.jar, webservices-extra-api.jar, OpenDS.jar,
je.jar, mfwk_instrum_tk-2.0.jar, xercesImpl.jar, jss4.jar,
esapiport.jar, jdmkrt.jar, je.jar, json.jar, asm-3.1.jar,
commons-logging-api-1.1.jar, rome-1.0.jar,jdom.jar,
commons-collections-3.2.jar, commons-fileupload-1.2.jar,
backport-util-concurrent-2.2.jar, commons-beanutils-1.6.jar,
icefaces.jar, icefaces-comps.jar, commons-logging-1.1.1.jar,
commons-digester-1.8.jar, icefaces-facelets.jar,
el-api-1.0.jar, jersey-bundle-1.1.1-ea-SNAPSHOT.jar,
oauth-signature-1.1.5-ea-SNAPSHOT.jar,
oauth-server-1.1.5-ea-SNAPSHOT.jar,
oauth-client-1.1.5-ea-SNAPSHOT.jar
%% 2.3 Obtaining db.jar
%% 2.4 Obtaining testng-5.9-jdk15.jar
%% 2.5 Obtaining fmsae.dll, fmsae64.dll and agent-csdk
%% 2.6 Obtaining Open Message Queue binaries, imq.jar and jms.jar
%% 2.7 Obtaining click.jar and click-extras.jar
%% 2.8 Obtaining ant-contrib-1.0b3.jar
%% 2.9 Obtaining commons-codec-1.3..jar
%% 2.10 Obtaining jsr311-api-1.1.jar
%% 2.11 Obtaining jstl.jar
%% 2.12 Obtaining jsf.jar, jsf-impl.jar

%% 3. Building the workspace
%% 3.1 build target
%% 3.2 doc target
%% 3.3 clean target
%% 3.4 demo target
%% 3.5 demo-clean target
%% 3.6 war target
%% 3.7 war-clean target
%% 3.8 usage target

%% 4. Building the demo

%% 1. Build requirements

The OpenSSO workspace uses Apache Ant as the build tool. The build scripts
in this workspace use features not present in releases of Ant prior to 1.6.
Thus, in order to build this workspace you must have Ant version 1.6.5 or above
installed and available in your system path.

The sources in this workspace should be compiled using JDK 5.0 with the source
and target levels set to "1.4". In order to allow this, you must ensure that
JDK 5.0 is present in your system path and the JAVA_HOME environment variable
is setup correctly pointing to its location.

%% 2. Library dependencies

The OpenSSO sources depend upon a few third-party libraries that are not
included as a part of the workspace and must be obtained directly from
the library vendor or distributor. Some of these libraries are available in
source distribution form and must be built locally before they can be used.
The libraries needed for compiling OpenSSO sources are:

- Java EE 5 SDK: j2ee.jar, mail.jar
- SUN shared library jars: jaxb-api.jar, jaxb-impl.jar,
jaxb-libs.jar, jaxb-xjc.jar, jaxrpc-impl.jar, jaxrpc-spi.jar,
jaxrpc-api.jar, activation.jar, saaj-api.jar, saaj-impl.jar,
relaxngDatatype.jar, xmlsec.jar, xalan.jar, xsdlib.jar,
FastInfoset.jar, jsr173_api.jar, webservices-api.jar,
webservices-rt.jar, webservices-tools.jar, webservices-extra.jar,
webservices-extra-api.jar, OpenDS.jar, je.jar,
mfwk_instrum_tk-2.0.jar, xercesImpl.jar, jss4.jar
- SleepyCat Berkeley DB version 4.2.52: db.jar
- TestNG version 5.9 : testng-5.9-jdk15.jar
- Secure Attribute Exchange API: fmsae.dll and fmsae64.dll
- Open Message Queue: mq4_4-v2-AIX.zip,mq4_4-v2-Linux_X86.zip,
mq4_4-v2-SunOS_X86.zip,mq4_4-v2-SunOS.zip,
mq4_4-v2-WINNT.zip,imq.jar and jms.jar
- Apache Commons Codec: commons-codec-1.3.jar

Once these libraries are available, they should be placed under the
"opensso/products/extlib" directory of your workspace. Any library placed
in this directory is automatically included in the classpath during the
compilation phase of the build process.

The following subsections briefly describe how these libraries may be
obtained. These instructions are provided for your convenience only and
are not intended to replace or invalidate the procedures/guidelines set
by the library vendor or distributor for obtaining those libraries. Before
you follow these instructions, you must agree to abide by any terms and
conditions set forth by the library vendor or distributor. In case any of
these instructions are in contradiction to such terms or conditions, you
must disregard those instructions and instead follow the ones provided by
the library vendor or distributor in accordance with their terms and
conditions.

%% 2.1 Obtaining j2ee.jar and mail.jar

The j2ee.jar and mail.jar library can be obtained from Java EE 5 SDK.
Follow these steps to obtain the J2EE SDK:

2.1.1 Open the web page: http://java.sun.com/javaee/downloads/index.jsp
2.1.2 Depending on your choice of platform, you may choose to download any
one of the three distribution types available under Java EE 5 SDK
Update 1.
2.1.3 Extract or extract and install the downloaded file as necessary to
have the SDK available on your system.

Once the J2EE SDK is installed, you can get the javaee.jar and mail.jar from
the lib directory of this SDK. You must rename javaee.jar to j2ee.jar when
copying it to the "opensso/products/extlib" directory of your workspace.

%% 2.2 Obtaining SUN shared library jars
Those libraries can be obtained by downloading opensso-sun-extlib.zip from
http://download.java.net/general/opensso/extlib/latest/opensso-sun-extlib.zip

Extract the zip, you can get all those shared library jars.

%% 2.3 Obtaining db.jar

The Sleepycat library db.jar is not distributed in the binary form. However,
this can be built using the source distribution provided by Sleepycat
Software. Follow these steps to obtain the db.jar library:

2.3.1 Open the web page: http://www.oracle.com/technology/software/products/berkeley-db/db/index.html
2.3.2 Under "4.x Releases", click "Berkeley DB 4.2.52 NC.tar.gz" link under
4.2.52, this will download the source distribution of Berkeley DB.
2.3.3 Extract the sources in a convenient location.
2.3.4 To build the entire distribution follow the instructions provided in
the docs/index.html by opening that file in a browser and clicking
on the appropriate link under "Building Berkeley DB" section as
applicable for your platform. The rest of the instructions in this
section describe how this distribution can be built on a unix platform.
2.3.5 Enter the directory db-4.2.52.NC/build_unix and issue the command:
../dist/configure --enable-java
for this command to work, you will need a C compiler along with
development utilities like gmake, autoconf and libtool available on
your on your system.
2.3.6 Once this command completes successfully, issue the following command
to compile the source distribution:
gmake
Note that you do not have to install the distribution for obtaining
the desired library.

Once this process is complete, the db.jar library can be obtained from
under the db-4.2.52.NC/build_unix directory.

%% 2.4 Obtaining testng-5.9-jdk15.jar

Download testng-5.9.zip from http://testng.org/testng-5.9.zip; unzip it and
testng-5.9-jdk15.jar in the base directory.

%% 2.5 Obtaining fmsae.dll, fmsae64.dll and agent-cdsk

Download opensso.zip from
http://download.java.net/general/opensso/nightly/latest/opensso/opensso.zip
Save the zip file locally, unzip it, then get fmsae.dll and fmsae64.dll from
libraries/native/dll and copy it into the opensso/products/extlib directory
in your workspace. Copy the agent-csdk subdirectory, and contents from
libraries/native to opensso/products/extlib.

%% 2.6 Obtaining Open Message Queue binaries, imq.jar and jms.jar

2.6.1 Open the web page: https://mq.dev.java.net/downloads.html
2.6.2 Depending on your choice of platform, you may choose to download any
one of the available distribution types available under Open MQ 4.4
Binary Downloads.
|----mq4_4-v2-Linux_X86.zip
| (Open Message Queue binaries for x86 linux)
|
|----mq4_4-v2-SunOS_X86.zip
| (Open Message Queue binaries for x86 Solaris)
|
|----mq4_4-v2-SunOS.zip
| (Open Message Queue binaries for sparc Solaris)
|
|----mq4_4-v2-WINNT.zip
| (Open Message Queue binaries for Windows)
|
|----mq4_4-v2-AIX.zip
| (Open Message Queue binaries for AIX)

2.6.3 Extract the downloaded file as necessary to get the
imq.jar and jms.jar under /imq/lib directory

%% 2.7 Obtaining click.jar and click-extras.jar
2.7.1 Visit http://click.sourceforge.net/, click on the Download hyperlink
(under the Click tree) on the left panel
You will be brought to sourceforge.net with the list of click binaries.
2.7.2 Download click-1.4.2.zip
2.7.3 Unzip this zip file in a temporary directory
2.7.4 copy /click.1.4.2/dist/click-1.4.2.jar to
/opensso/products/extlib/click.jar
2.7.5 copy /click.1.4.2/dist/click-extras-1.4.2.jar to
/opensso/products/extlib/click-extras.jar

%% 2.8 Obtaining ant-contrib-1.0b3.jar
2.8.1 Visit http://sourceforge.net/project/showfiles.php?group_id=36177
2.8.2 Under "Latest File Releases" , click on the link "Download".
You wil be brought to a page with list of ant-contrib binaries.
2.8.3 Download ant-contrib-1.0b3-bin.zip
2.8.4 Unzip this zip file in a temporary directory.
2.8.5 copy /ant-contrib/ant-contrib-1.0b3.jar to
/opensso/products/extlib/ant-contrib-1.0b3.jar

%% 2.9 Obtaining commons-codec-1.3..jar
2.9.1 Visit http://commons.apache.org/downloads/download_codec.cgi
2.9.2 Download one of the Binary selections (e.g., 1.3.tar.gz)
2.9.3 Uncompress (and un-tar, in the case of 1.3.tar.gz) the file in
a temporary directory.
2.9.4 Find the commons-codec-1.3.jar file and copy it to
/opensso/products/extlib/commons-codec-1.3.jar

%% 2.10 Obtaining jsr311-api-1.1.jar
2.10.1 Download from
http://download.java.net/maven/2/javax/ws/rs/jsr311-api/1.1/jsr311-api-1.1.jar

%% 2.11 Obtaining jstl.jar
2.11.1 Download from
http://mirrors.ibiblio.org/pub/mirrors/maven2/jstl/jstl/1.1.2/jstl-1.1.2.jar
%% 2.12 Obtaining jsf.jar, jsf-impl.jar
2.12.1 Download
https://javaserverfaces.dev.java.net/files/documents/1866/138058/mojarra-1.2_13-binary.zip
2.12.2 Unzip it and the jars are in lib directory.

%% 3. Building the workspace

The workspace build system offers many build targets. You can view the
available targets by issuing the ant command from the root of the
workspace. The default target that is executed is the usage target which
displays a brief description about the other targets. Currently the main
targets available in the workspace are:

- build : compiles the sources
- doc : creates javadocs
- clean : deletes the generated files
- demo : builds the demo application
- demo-clean : deletes generated demo files
- war : builds the WAR
- war-clean : deletes generated WAR
- usage : displays this usage message

%% 3.1 build target

The build target involves the following processing:

3.1.1 Creation of build output directories such as
/built
/built/classes
/built/resources
/built/docs
/built/docs/api

3.1.2 Compiles all the classes present in the source directory to the
built/classes directory. The compilation debug flag is set to
"-g:none" but can be changed by defining the following two properties
in your user level property file $HOME/.opensso:

- build.debug: allowed values are on and off. Example: build.debug=on

- build.debuglevel: one or more of lines, vars, source as a comma
separated list. Example: build.debuglevel=lines,source

3.1.3 Transfers the resource and xml files from the resources and xml
directories to the built area under the built/resources directory.
The two exceptions are:

- the file sms.dtd is copied over to the classes directory under
the package com/sun/identity/sm as per its defined location for
reference by other xml files.

- the properties files Services.properties, DSConfig.properties,
ums.properties, sso.properties, SMS.properties and
authentication_util.properties are combined into a single
properties file called amSDK.properties.

The xml files are tag-swapped to change the XML_ENCODING tag with
the value ISO-8859-1.

%% 3.2 doc target

The doc target involves the following processing:

3.2.1 Creation of build output directories such as
/built
/built/classes
/built/resources
/built/docs
/built/docs/api

3.2.2 Executes the javadoc tool with output directory set to built/docs/api
and includes the following packages:
com/iplanet/sso/**
com/iplanet/dpro/**
com/sun/identity/session/**

The "**" indicate all sub-packages underneath the current package.

%% 3.3 clean target

The clean target removes all the build output directories.

%% 3.4 demo target

The demo target first invokes the build target and then delegates the
further processing to the build.xml file present under the demo directory.
This target cannot be executed directly unless certain configuration tasks
are performed as described in the file demo/README. Please refer to this file
for further details on the configuration tasks needed prior to building the
demo.

%% 3.5 demo-clean target

Issues a clean to the build.xml file present under the demo directory. This
target is useful in case you are interested in rebuilding the demo without
rebuilding the entire OpenSSO distribution. By issuing the demo-clean target
the build output area for the OpenSSO distribution is not changed and only
the demo related build output area is cleaned.

%% 3.6 war target

The war target first invokes the build target and then delegates the
further processing to the build.xml file present under the war directory.
A deployable WAR file will be created under federation/openfm/built/war/dist
directory after this target is successful executed.

%% 3.7 war-clean target

Issues a clean to the build.xml file present under the war directory. This
target is useful in case you are interested in rebuilding the war without
rebuilding the entire OpenSSO distribution. By issuing the war-clean target
the build output area for the OpenSSO distribution is not changed and only
the war related build output area is cleaned.

%% 3.8 usage target

Displays a list of available targets along with a brief description of
each available target for quick reference.

%% 4. Building the demo

Before building the demo, please follow any instructions described in the
file demo/README. This file also describes the necessary background
information regarding the demo and the details of how it works.