Copyright 2004 The Apache Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


                  A  P  A  C  H  E    J  E  T  S  P  E  E  D


  What is it?
  -----------

  Jetspeed is an Enterprise Information Portal framework aiming to provide :

  * an efficient multi-device user customizable portal interface
  
  * a portal independant "portlet" API used for developing customizable
    components that can be integrated into any compatible portal

  * a lightweight syndication system that can be used as a simple distributed
    HTTP content management system
    
  Jetspeed will not provide a full content management system but will 
  provide bridges to external CMS systems like Apache Slide or Infozone Prowler
  
  Where is it?
  ------------

  The home page for the Apache Jetspeed project can be found in the Apache Java 
  Project web site (http://portals.apache.org/jetspeed-1/). There you also find 
  information on how to download the latest release as well as all the other 
  information you might need regarding this project.

  Requirements
  ------------

  Jetspeed is implemented as a Java web application.
  The following requirements exist for installing it:

   o  A Java 1.2 or later compatible virtual machine for your operating system.

   o  Server API 2.2 compatible Servlet Engine.
  

  Installation Instructions for the war distribution
  -----------------------------------------------------

  Read the INSTALL file in this directory for the installation instructions.

  The documentation available as of the date of this release is
  included in the WAR file.

  Look for the most updated documentation on the Apache Jetspeed web site under
  the Apache Java Project (http://portals.apache.org/jetspeed-1/).

  Installation Instructions for the source distribution
  -----------------------------------------------------

  Read the INSTALL file in this directory for the installation instructions.

  The documentation available as of the date of this release is
  included in the "docs/" directory.

  Look for the most updated documentation on the Apache Jetspeed web site under
  the Apache Java Project (http://portals.apache.org/jetspeed-1/).


  Release Notes and Known issues
  ------------------------------

  For additional information on this release, please read the NOTES file.


  Licensing and legal issues
  --------------------------

  For legal and licensing issues, please read the LICENSE file.


  Usage Warnings
  --------------

  Please, read the WARNING file before continuing.


  Thanks for using Apache Jetspeed.

==============================================
Jetspeed 1.5 was released on April 22, 2004.
==============================================

* New Features *

 1. Security refactored to allow assigning roles within groups
 2. Jetspeed 1.5 Tutorial moved off of Bluesunrise and converted to Maven documentation format.
 3. Jetspeed Maven Plugin for creating and working with Jetspeed-based projects
 4. Build converted to Maven. Ant build deprecated.
 5. Jetspeed site converted to use Maven, and moved to http://portals.apache.org/jetspeed-1
 6. Jetspeed becomes a part of the Apache Portals project http://portals.apache.org
 7. Email Portlet
 8. Redirect Portlet
 9. Enhanced portlet filtering on the layout customize
10. New skins and updated look and feel of the default portal
11. Portlets and decorators (controls) can now be completely hidden if user doesn't have secure access to the portlet.
12. GenerciMVC portlet now can render in parallel with other portlet on the page
13. Added filtering on portlet registry browser
14. Drag and drop controller for the layout designer  
15. Upgrade to Torque 3.1 and Torque Plugin

* Bug Fixes *

    - See FIXES.html for a full list of fixes in this release

==============================================
Jetspeed 1.4 was released on October 29, 2003.
==============================================

* New Features *

    - Search service refactored with pluggable document handlers
    - Added parameter style jsp tag
    - Logging converted from Turbine to Commons + log file viewer portlet. Contributed by Harald Ommang
    - Improved portlet skinning capabilities. Contributed by Aurelien Pernoud
    - WebClippingPortlet. Contributed by Marco Mari
    - MyPages functionality
    - Java applet portlet
    - BASICAuthIFrame portlet
     - Implemented portlet icon functionality
     - Polish language resource bundle

* Bug Fixes *

    - See FIXES.html for a full list of fixes in this release

==============================================
Jetspeed 1.4b4 was released on April 25, 2003.
==============================================

* New Features *

    - Registry editors (portlet, security, client, skin). Contributed by Jeremy Ford
    - Ant task for overriding properties. Contributed by Eric Pugh
    - Maven jetspeed plugin. Contributed by Eric Pugh
    - MVC portlet. Joint effort by Scott Weaver and Tod Kuebler
    - JSP Stock Quote Portfolio demo portlet
    - Greatly improved international support (change language portlet + custom localization service)
    - Jetspeed questionnaire
    - Forwarding tool

* Jetspeed Security *

    - Plugged security hole allowing unathorized access to psml
    - Default security ref may now be defined for newly created portal resources

* Misc *

    - Access to skins, references and security refs in the customizer is now security driven
    - Sample Hypersonic database now comes pre-populated with psml
    - Directory based skin support for images

* Bug Fixes *

    - See FIXES.html for a full list of fixes in this release


================================================
Jetspeed 1.4b3 was released on December 15, 2002
================================================
Jetspeed 1.4b3 is a patch to version 1.4b2 fixing two sets of bugs:

Bugs 14907, 15000 - Security hole bugs fixed. 
                     Users with admin role can no longer access admin resources.

Bugs 14917, 15265 - Xerces does not handle correctly file paths on some platforms (Novell),  Windows with spaces. 
                    This was causing many Windows-based installs to fail.


===============================================
Jetspeed 1.4b2 was released on December 9, 2002
===============================================

* New Features *

This release is full of new features thanks in great part to a very welcome new committer, Mark Orciuch. Here is a list of new features implemented by Mark:

    - Parameter Presentation Styles - Data Entry Widgets including Date/Calendar, ListBox, CheckBoxGroup, TextArea, Custom JSP, Custom Velocity
    - Portlet Preview Mode
    - Portlet Usage Logging
    - Password Expiration 
    - Online Profile Import/Export
    - Print Friendly Mode
    - Filtering in User Browser and Psml Browser 


* Documentation *

Jetspeed 1.4b2 introduces a new set of documentation to more fully cover the changes made to version 1.4. We have added the following documents:

    - New 100+ page Jestpeed Tutorial 
    - JPortal Application Examples, accompanies the tutorial
    - Jetspeed Axis Integration Guide
    - New Registry Documentation
    - New Layout Documentation
    - New Client Media Documentation


* Dependencies *

We updated as many Jars as we could to the latest versions without breaking the dependencies.
Most importantly, we are now again in sync with the latest releases of: 

    Torque 
    Turbine 
    Commons
    Hypersonic DB


* Improved JSP Support *

Jetspeed JSP Tag library updated to support internationalization and Jetspeed Links. JSP templating engine updated to operate like Velocities, supporting the same media/language/country fallback algorithm.


* Client and Media Type Registries *

Two new registries have been added to better support new Media Types and Client agents.


* Jetspeed Security *

Further enhancements to security:
    - New LDAP Security Implementation from Ender Kilicoglu
    - Added "owner rule" to only allow access to the owner of a portal resource
    - Cleaned up security in default site
    - Add Security to References


** Misc **

    - Allow Customization of Portlet Control per Portlet
    - New File Cache utility
    - CheckStyle added to build file

==============================================
Migration Issues from Jetspeed 1.4b1
==============================================

The following are known migration issues:

1. Add a new column on TURBINE_USER table:

PASSWORD_CHANGED TIMESTAMP

2. Torque has been upgraded. See issue list here:

http://portals.apache.org/jetspeed-1/supporting-projects.html

3. If you're using the Hypersonic SQL db, the primary key id columns have
been changed to auto-increment. To not use auto-increment, change your security-schema.xml 
back to using the ID_TABLE, add the new column, and regenerate.
You must then add the new column to your hypersonic database in production by edition jetspeed.script.

4. For XSLPortlet, "stylesheet.html" parameter has been renamed to "stylesheet.text/html".

==============================================
Other known issues and limitations
==============================================

1. In order to support multiple instances of a portlet per page, the parent abstract portlet must descend from
AbstractInstancePortlet (see Bugzilla issue# 13696).

2. Password reminder and password encryption features are mutually exclusive. Jetspeed passwords are encrypted
using a one-way encryption technique and therefore cannot be used in the password reminder email (see Bugzilla
issue# 19680).

3. If "action" and/or "template" portlet parameters are not declared as hidden, customizing the portlet may render it unusable (see Bugzilla issue #14830).

4. When "Menu pane" or "Tab pane" is selected as layout, "Add Portlet" button is disabled. This a voluntary limitation rather than bug. As workaround, set layout to something like "Single column", add portlets and switch back to "Menu pane".

5. Auto-login feature does not work when using localhost for the host name. A real domain name must be used or an alias must be created in hosts file (for example: 127.0.0.1 -> www.localhost.com).

6. The setAttribute does not work with no-cache option for dbpsml (see Bugzilla bug# 21063).

7. You may get a compile error on BaseLDAPObject in Japanese enviroment (see Bugzilla bug# 19488).

8. You may get schema violation on OpenLDAP 2.1.12 (see Bugzilla bug# 18694).

9. XML encoding parsing in URLFetcher may fail if 'encoding="' uses a single quote or if there's space before or after '=' (see Bugzilla bug# 13255).

==============================================
Tested configurations for release 1.4 and 1.5
==============================================

                                        Servlet         
Operating System        JDK             Container               Comments/Issues
----------------        ---             ---------               ---------------
Windows 2000            1.4.1_03        Tomcat 4.1.24
Windows 2000            1.3.1_02        Tomcat 4.1.24
Windows 2000            1.3.1_02        Tomcat 3.3.1a           XML parser errors
Windows 2000            1.2.2           WebSphere 3.5.6         xalan-2.3.1, xerces-2.0.2, xml-apis on the app server classpath
Windows 2000            1.3.1           WebSphere 4.0.5         xalan-2.3.1, xerces (WAS supplied), xml-apis, crimson-1.1.3 on the app server classpath
Linux                   1.4.1_01        Tomcat 4.0.6

==============================================
Logging usage notes for release 1.4
==============================================

The final release of Jetspeed uses Log4J directly, instead of commons logging or Turbine logging facilities.
Log4J is wrapped in the classes org.apache.jetspeed.services.JetspeedLogFactoryService and JetspeedLogger.
The JetspeedLoggingService introduced in 14b4 is now rewritten to log through these new features, in order
to capture the logging from Turbine. With these changes, all references to the Turbine Log class is removed 
from all parts of Jetspeed except JetspeedLoggingService.
It (and the TurbineLoggingService) will be gone in the next version of Turbine. At that time, the 
JetspeedLoggingService is no longer needed.

Logging can now be configured via log4j.properties or log4j.xml.

For more details, see the Configuration Guide and Coding Spec.

==============================================
DB Psml import usage notes for release 1.4
==============================================

Jetspeed comes configured with Castor Psml Manager service which uses files to store psml. However, sample
Hypersonic database has been populated with psml profiles for convenience. To switch to DB Psml Manager,
make the following changes in jr.props:

# services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.CastorPsmlManagerService
services.PsmlManager.classname=org.apache.jetspeed.services.psmlmanager.db.DatabasePsmlManagerService

When importing psml profiles into database, Psml Importer will not import over existing psml. To change this
behaviour, modify the import task as follows:

        <java fork="true" classname="org.apache.jetspeed.services.psmlmanager.PsmlImporter" >
            <arg value="false"/>        
            <classpath>
                <pathelement location="${build.dest.dir}"/>
                <path refid="classpath"/>
                <pathelement location="${junit.jar}"/>
                <pathelement location="${hsql.jar}"/>
            </classpath>
        </java>

One of the common problems with import is key generation. This may not be apparent during the import process.
Actually, you may see message about successful import even if it didn't work. In these cases, it's best to
turn on Torque debugging in tr.props to see what went wrong:

services.LoggingService.logforj.log4j.rootCategory = WARNING, logforj

Then check the webapp/WEB-INF/log/jetspeed.log immediately after running import task. Actually, the method of
activating Torque logging will probaly change in Beta 5 but this method should still work in Beta 2 thru Beta 4.

In release 1.5, Jetspeed ships with an on-line utility to do the initial db psml population. You should configure
Jetspeed with DatabasePsmlManagerService, start it, login as an administrator and invoke the following URL:

http://localhost:8080/jetspeed/portal/template/ImportPsml.vm

==============================================
References usage notes for release 1.4 and 1.5
==============================================

PSML Reference is a method of nesting psml resource within another psml resource. This is roughly comparable to 
object linking and embedding concept (for those familiar with M$ Windows). The customizer allows to select
a reference to another psml resource and it shows it just like another portlet. When portal page containing
references is rendered, the references are rendered as well. The most important feature of a reference is that
when the psml being referred to (source of the reference) is changed, all psml referring to it can see the change.
You may utilize references to create some interesting "newspaper layout" like effects. Here are known issues and 
limitations:

    1. The reference browser displays all available psml resources (including admin's) and therefore access to
    the "Add Reference" button is available to admin role only by default.

    2. A reference may only be included if it has a defined security ref. You may still select the reference
    for inclusion in your profile but the request will be ignored if the selected psml contains no top level
    security ref (a warning will be logged in jetspeed.log).

    3. A reference is read-only which means that you cannot customize the psml included as a reference.

    4. Because of the way references are being stored in memory, when source psml is changed, the psml referring to
    it will not see the change until it is refreshed (i.e. upon psml cache expiration).

Some or all of the above shortcomings will be addressed in the future releases of Jetspeed.

==============================================
JBoss usage notes for release 1.4b4
==============================================

It is possible to use Jetspeed with JBoss. Here are steps required to do so (compiled by Werner Ramaeker and also
available here: http://www.shiftat.com/blog/page/werner/20021027):

1. Get JBoss-3.0.3_Tomcat-4.0.5 from the JBoss site at sourceforge. 

2. Check out the current Jetspeed version from CVS. 

3. Build Jetspeed using the $JETSPEED_HOME/build/build.xml with ant deploy to generate the jetspeed.war 

4. Create a directory called jetspeed.ear in the $JBOSS_HOME/server/default/deploy directory 

5. Add a directory called META-INF to the jetspeed.ear folder, in the META-INF folder put the following application.xml 

<application>                             
 <display-name>Jetspeed on JBoss</display-name>                             
  <module>                             
   <web>                             
     <web-uri>jetspeed.war</web-uri>                             
     <contextRoot>/jetspeed</contextRoot>                             
   </web>                             
  </module>                             
</application>                            

6. In the jetspeed.ear directory : unzip the jetspeed.war file into a directory called jetspeed.war (explode the war file) 

7. Remove the following files from $JBOSS_HOME/server/default/lib/ : castor.jar, hsqldb.jar, hsqldb-plugin.jar 

8. Remove the following file from $JBOSS_HOME/server/default/deploy/ : hsqldb-service.xml 

9. Start JBoss from the $JBOSS_HOME/server/default/bin/run.sh or run.bat 

Remark: 

In case you need your Jetspeed version to contact the internet over a proxy for example to get the newsfeeds : be sure to start JBoss's VM with the proxy parameters as follows : 

-DproxySet=true -DproxyHost="proxyserver name/IP" -DproxyPort="proxyserver port" 

Here's another JBoss related thread: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=18415.

==============================================
Commons logging usage notes for release 1.4b4
==============================================

The final release of Jetspeed will use commons logging instead of turbine logging facilities. As an interim
solution, Jetspeed ships with a custom logging service that allows to use log4j directly. To activate:

        1. Add init-param "logging" in web.xml and set it to "org.apache.jetspeed.services.logging.JetspeedLoggingService".
        2. Change this in tr.props:
                services.LoggingService.classname = org.apache.jetspeed.services.logging.JetspeedLoggingService
                services.LoggingService.default = jetspeed
        3. Add this in tr.props:
                services.LoggingService.log4j.properties = /WEB-INF/conf/log4j.properties
 
Now you can configure logging via log4j.properties.

==============================================
Maven usage notes for release 1.4b4
==============================================

Maven build is a work in progress and will be complete for the final release. The major part still missing from
the Maven build is creation of the Torque object model and castor registry peers. So theoretically, if you use
ant build to generate these once, you can start using maven from that point on. Also, in CVS, there's a maven
jetspeed plugin (/src/plugins-build/jetspeed) which offers various options on building custom portals based on
jetspeed .war file or binary distribution (product of maven dist:build). In the future, this plugin will be
distributed with maven or available through maven-plugins.sourceforge.net.

The maven build was tested with version 1.0 Beta 9 of Maven.

The maven build is complete as of version 1.5. Tested with Maven 1.0 RC2.

==============================================
Eclipse usage notes for release 1.4b4
==============================================

The following is a list of notes when using Eclipse and Jetspeed:

1. Eclipse .project and .classpath files may be (re)generated using 'maven eclipse' command.

2. When running Jetspeed unit tests in Eclipse, make sure to set the working directory
to Jetspeed's build directory: Run -> Arguments -> Working Directory -> Local Directory -> \jakarta-jetspeed.

3. To run Ant tasks which require recompiling Jetspeed classes, you must specify the following argument in the task definition:
External Tools -> Ant Build -> <target name> -> Arguments -> -Dbuild.compiler=org.eclipse.jdt.core.JDTCompilerAdapter

These were tested with Eclipse 2.1.1 and JDK 1.3.

 