You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by dl...@apache.org on 2005/11/22 01:11:50 UTC
svn commit: r348039 [2/4] - in /portals/jetspeed-2/trunk/xdocs: ./ guides/
images/ style/
Modified: portals/jetspeed-2/trunk/xdocs/getting-started.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/getting-started.xml?rev=348039&r1=348038&r2=348039&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/getting-started.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/getting-started.xml Mon Nov 21 16:10:44 2005
@@ -1,830 +1,212 @@
<?xml version="1.0"?>
<!--
- 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.
+ 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.
-->
<document>
- <properties>
- <title>Getting Started with Jetspeed 2</title>
- <subtitle>Getting up and running quickly</subtitle>
- <authors>
- <person name="David Sean Taylor" email="taylor@apache.org" />
- <person name="Ate Douma" email="ate@apache.org" />
- <person name="David Le Strat" email="dlestrat@apache.org" />
- </authors>
- </properties>
- <body>
- <section name="Requirements">
- <p>
- It is expected that the user is familiar with both the <a href="http://maven.apache.org">Apache Maven</a>
- project tool and the <a href="http://ant.apache.org">Apache Ant</a> build tool.
- </p>
- <ul>
- <li>
- <a href="http://ant.apache.org/bindownload.cgi">Ant 1.5</a>
- or higher
- </li>
- <li>
- <a href="http://maven.apache.org/start/download.html">
- Maven 1.0.2
- </a>
- or higher
- </li>
- <li>Java 1.4.2_02 or higher</li>
- <li>
- Servlet 2.3:
- <br />
- Tomcat 5.0.30 (or higher)
- <br />
- <b>or</b>
- <br />
- Tomcat 5.5.8 (or higher)
- </li>
- </ul>
- </section>
- <section name="Naming Conventions and Basic Assumptions">
- <subsection name="Basic Assumptions">
- <ul>
- <li>
- Unless otherwise specified, you should be running all maven build commands
- from within the Jetspeed directory (if you are just building Jetspeed) or
- from within your custom portal directory.
- </li>
- <li>
- You must use "/" as a file seperator on both *nix and windows, e.g. c:/windows, and /home.
- </li>
- </ul>
- </subsection>
- <subsection name="Naming Conventions">
- <p>
- Below is a listing of common conventions used within this document.
- </p>
- <p>
- Variables are represented as such, ${<i>some_variable</i>}. This may signify a setting in jetspeed or
- may represent a setting within your environment.
- <br/>
- Properties files are also capable of using ${some_variable} within them. So, for example,
- ${org.apache.jetspeed.server.home} references either a property defined further up in the
- properties file, that has been defined somehwere within the build process or defined
- in another build file within jetspeed.
- </p>
- <ul>
- <li>
- <b>${USER_HOME}</b>: This is the user's home directory. For Windows systems, this generally
- c:\Documents and Settings\${userName} where ${userName} is the name you log into windows as.
- <br/>
- ${USER.HOME} is synonymous with ${USER_HOME} within this document.
- </li>
- <li>
- <b>${CATALINA_HOME}</b>: This should point to the location of your tomcat installation, e.g. <i>c:/tomcat</i>.
- </li>
- </ul>
- </subsection>
- <subsection name="Subversion (SVN)">
- <p>
- <a href="http://subversion.tigris.org">Subversion (SVN)</a> is becoming the standard source and version control mechanism for Apache projects. SVN is
- very similar CVS. For those user's on Windows system who prefer non-command line access we suggest using
- <a href="http://tortoisesvn.tigris.org">TortoiseSVN</a> which plugs into your Windows Explorer view. For those
- using the Eclipse IDE, there is a <a href="http://subclipse.tigris.org">plugin</a> available for SVN access.
- </p>
- </subsection>
- <subsection name="Maven">
- <p>
- We will not go into the specifics of Maven as that is beyond the scope of this document. However, here are a few bits of standard
- maven jargon we feel is important for you to know.
- </p>
- <p>
- You will see mention of a <i>maven repository</i> in this document. When you install Maven the .maven/ directory is created in your
- ${USER_HOME) directory.
- <br/>
- Under .maven/ you will see a <i>repository</i> directory. This is were Maven stores all the jars it downloads when you run your builds. This is
- also were Maven puts your jars.wars you build under the format of ${groupId}/${projectId}/jars/${projectId}-{$version}.jar for jar files and
- ${groupId}/${projectId}/wars/${projectId}.war for war files. The ${groupId}, ${projectId} and ${version} variables are discussed later on in this
- document. Jars/wars will also be created in your project in the <i>/target</i> directory.
- </p>
- </subsection>
- </section>
- <section name='1. Get Maven Ready'>
- <p>
- If you have not already done so, download and install Maven.
- </p>
- </section>
- <section name='2. Jetspeed build and maven-plugin Properties'>
- <p>
- If you are going to build Jetspeed directly from the source or want to setup a custom portal you need to set a
- few properties.
- </p>
- <p>
- Creating your own custom portal is very easy with the maven plugin provided by Jetspeed 2. And, it is used when
- you build jetspeed from source as well. In fact, the jetspeed-2 build procedure is just one example of a custom
- portal configuration and setup.
- </p>
- <p>
- The Jetspeed 2 maven-plugin defines default values for most of the properties you can set, but not all. When you
- download or checkout the jetspeed-2 source tree, you'll see it contains a project.properties file in the root
- folder overriding and setting some of these properties.
- </p>
- <p>
- As said before: not all properties are provided with a default value: you <i>must</i> specify a few yourself.
- And you'll most likely want to override some others.
- </p>
- <p>
- Set or override the build or maven-plugin properties in your <code>${USER_HOME}/build.properties</code> file.
- </p>
- <subsection name="Required Portal Configuration Properties">
- <table>
- <tr>
- <th>Property</th>
- <th>Description</th>
- <th nowrap="nowrap">Default value</th>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.home</code>
- </td>
- <td>
- The folder where the maven-plugin will (re)create or update your custom portal maven project configuration
- (with goal <code>j2:portal.conf.project</code>). This will be where you will be performing all of your future
- custom portal development.
- <br />
- Example: <code>/home/myportal/</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.groupId</code>
- </td>
- <td>
- The (maven) short name of your portal project group.
- <br />
- This value is used for the maven repository folder in which the project artifacts (like the portal war
- file) is stored.
- <br />
- Example: <code>myprojects</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.artifactId</code>
- </td>
- <td>
- The (maven) short name of your portal project.
- <br />
- This value is used for the portal war file and the (portal) web application context name.
- <br />
- Example: <code>myportal</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.name</code>
- </td>
- <td>
- The (maven) full name of your portal project.
- <br />
- This value is used by maven for generating JavaDoc titles.
- <br />
- Example: <code>My Test Portal</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.currentVersion</code>
- </td>
- <td>
- The current version of your portal project.
- <br />
- This value is used by maven as name postfix for the generated artifacts.
- <br />
- Example: <code>1.0</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- </table>
- </subsection>
- <subsection name="Optional Portal Configuration Properties">
- <p>
- The following properties all specify a subfolder of the <code>${org.apache.jetspeed.portal.home}</code>
- location as defined above.
- </p>
- <table>
- <tr>
- <th>Property</th>
- <th>Description</th>
- <th nowrap="nowrap">Default value</th>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.conf.dir</code>
- </td>
- <td>
- The folder where the maven-plugin will generate and copy application server specific configuration files
- as a tomcat application context descriptor.
- <br />
- This folder and its contents is created or updated by plugin goal <code>j2:portal.conf.tomcat</code>.
- </td>
- <td>
- <i>target/portal-conf</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.sql.dir</code>
- </td>
- <td>
- The folder where the maven-plugin will generate and copy portal and database server specific sql DDL and
- DML scripts.
- <br />
- This folder and its contents is always (re)created by plugin goal <code>j2:portal.conf.sql</code>.
- </td>
- <td>
- <i>target/portal-sql</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.db.dir</code>
- </td>
- <td>
- The folder where the maven-plugin will create its build-in HSQLDB database(s).
- <br />
- This folder and its contents is created or updated by plugin goal <code>j2:start.production.server</code>
- or <code>j2:start.test.server</code>.
- </td>
- <td>
- <i>target/portal-db</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.webapp.dir</code>
- </td>
- <td>
- The folder where the maven-plugin will copy the standard jetspeed web application resources.
- <br />
- This folder and its contents is created or updated by plugin goal <code>j2:portal.copy.webapp</code>.
- </td>
- <td>
- <i>target/${org.apache.jetspeed.portal.artifactId}</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.portal.target.dir</code>
- </td>
- <td>
- The folder where the maven-plugin will generate and copy runtime portal configuration files.
- <br />
- These configuration files contain values derived from build/plugin properties for the portal and OJB.
- <br />
- This folder and its contents is created or updated by plugin goal <code>j2:portal.conf.jetspeed</code>
- and goal <code>j2:portal.conf.ojb</code>.
- </td>
- <td>
- <i>target/${org.apache.jetspeed.portal.artifactId}</i>
- </td>
- </tr>
- </table>
- </subsection>
- <subsection name="Required Application Server Properties">
- <p>
- <i>
- Note: The maven-plugin currently only supports the Tomcat Server 5.0.x or 5.5.x
- </i>
- </p>
- <table>
- <tr>
- <th>Property</th>
- <th>Description</th>
- <th nowrap="nowrap">Default value</th>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.server.home</code>
- </td>
- <td>
- The root folder of your Tomcat server installation.
- <br />
- Example: <code>${CATALINA_HOME}/</code>.
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.server.shared</code>
- </td>
- <td>
- The location of the shared jars in your Tomcat installation.
- <br />
- Example: <code>${org.apache.jetspeed.server.home}/shared/lib/</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.deploy.war.dir</code>
- </td>
- <td>
- The location of web applications in your Tomcat installation.
- <br />
- Example: <code>${org.apache.jetspeed.server.home}/webapps/</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.services.autodeployment.user</code>
- </td>
- <td>
- A Tomcat user with the manager role.
- <br />
- Used to access the Tomcat Manager application from within the portal, explained below.
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.services.autodeployment.password</code>
- </td>
- <td>
- The password of the Tomcat user above.
- <br />
- Used to access the Tomcat Manager application from within the portal, explained below.
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.catalina.version.major</code>
- </td>
- <td>
- The major version of the Tomcat server you are using: 5 or 5.5
- <br />
- Example: <code>5.5</code>
- </td>
- <td>
- <i>no default</i>
- </td>
- </tr>
- </table>
- </subsection>
- <subsection name="Optional Database Server Properties">
- <p>
- Jetspeed-2 and its maven-plugin uses, as well as provides, by default a HSQLDB database.
- </p>
- <p>
- If you want to use a different database you will need to override the following properties:
- </p>
- <table>
- <tr>
- <th>Property</th>
- <th>Description</th>
- <th nowrap="nowrap">Default value</th>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.database.default.name</code>
- </td>
- <td>
- The type of database you are using. Used for sql script generation with Torque.
- <br />
- Currently supported databases (with corresponding Torque target database name):
- <ul>
- <li>hsql (hypersonic)</li>
- <li>oracle (oracle)</li>
- <li>mysql (mysql)</li>
- <li>postgres (postresql)</li>
- <li>mssql (mssql)</li>
- </ul>
- </td>
- <td>hsql</td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.database.url</code>
- </td>
- <td>The jdbc connection url</td>
- <td>jdbc:hsqldb:hsql://127.0.0.1:9001</td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.database.user</code>
- </td>
- <td>The database user name to connect with.</td>
- <td>sa</td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.database.password</code>
- </td>
- <td>The database user its password to connect with.</td>
- <td>
- <i>empty</i>
- </td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.database.driver</code>
- </td>
- <td>The jdbc driver class name</td>
- <td>org.hsqldb.jdbcDriver</td>
- </tr>
- <tr>
- <td>
- <code>org.apache.jetspeed.production.jdbc.drivers.path</code>
- </td>
- <td>
- A Java classpath style path to the jdbc driver classes or jar(s) needed for connecting to the database.
- <br />
- Example: <code>/lib/ojdbc14.jar;/lib/nls_charset12.jar</code>
- </td>
- <td>
- <i>empty</i>
- </td>
- </tr>
- </table>
- </subsection>
- <subsection name="Example: A minimal custom portal configuration">
- <p>
- Make sure you have define at least the required properties as described above in your
- <code>${USER_HOME}/build.properties</code>. A minimal custom portal configuration using the default HSQLDB
- database can be something like:
- <source>
- <![CDATA[
-# required portal configuration properties
-org.apache.jetspeed.portal.home = /home/myportal/
-org.apache.jetspeed.portal.groupId = myprojects
-org.apache.jetspeed.portal.artifactId = myportal
-org.apache.jetspeed.portal.name = My Test Portal
-org.apache.jetspeed.portal.currentVersion = 1.0
+ <properties>
+ <title>Getting Started with Jetspeed 2</title>
+ <subtitle>Getting up and running quickly</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org" />
+ <person name="Ate Douma" email="ate@apache.org" />
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ <person name="Ron Wheeler"
+ email="rwheeler@artifact-software.com" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Requirements">
+ <p>
+ It is expected that the user is familiar with both the
+ <a href="http://maven.apache.org">Apache Maven</a>
+ project management tool and the
+ <a href="http://ant.apache.org">Apache Ant</a>
+ scripting utility.
+ </p>
+ <ul>
+ <li>
+ <a href="http://ant.apache.org/bindownload.cgi">
+ Ant 1.5
+ </a>
+ or higher
+ </li>
+ <li>
+ <a
+ href="http://maven.apache.org/start/download.html">
+ Maven 1.0.2
+ </a>
+ </li>
+ <li>Java 1.4.2_02 or higher</li>
+ <li>
+ Servlet 2.3 Engine:
+ <ul>
+ <li>Tomcat 5.5.8 or higher</li>
+ <li>Jetty</li>
+ <li>Websphere</li>
+ <li>Geronimo</li>
+ <li>JBoss</li>
+ </ul>
-# required application server properties
-org.apache.jetspeed.server.home = ${CATALINA_HOME}/
-org.apache.jetspeed.server.shared = ${org.apache.jetspeed.server.home}/shared/lib/
-org.apache.jetspeed.deploy.war.dir = ${org.apache.jetspeed.server.home}/webapps/
-org.apache.jetspeed.services.autodeployment.user = j2deployer
-org.apache.jetspeed.services.autodeployment.password = xxxxx
-org.apache.jetspeed.catalina.version.major = 5.5]]>
- </source>
- <i>
- Note: If you're going to build the default Jetspeed 2 portal directly from the source only the
- <code>org.apache.jetspeed.portal.home</code> property is required from the set of required portal
- configuration properties.
- </i>
- </p>
- </subsection>
- </section>
- <section name="3 Tomcat Configuration">
- <p>
- Jetspeed 2 can use the Tomcat Manager application for managing portlet applications with the Portlet Application
- Lifecycle Manager Portlet (PALM). To be able to do so it needs a configured Tomcat user with the predefined
- 'manager' role in the ${org.apache.jetspeed.server.home}/conf/tomcat-users.xml.
- </p>
- <p>
- A minimal example tomcat-users.xml can look like:
- <source>
- <![CDATA[
+ </li>
+ </ul>
+ </section>
+
+ <section name='1. Get Maven Ready'>
+ <p>
+ If you have not already done so, download and install
+ <a href="http://maven.apache.org/maven-1.x">Maven</a>
+ .
+ </p>
+ </section>
+ <section name='2. What Database do you want'>
+ <p>
+ Jetspeed's security model requires a database to
+ authorize users and to retain the user information.
+ Jetspeed security should work with any JDBC 2.0
+ compliant driver. The following databases are tested:
+ <ul>
+ <li>HSQLDB - Hypersonic SQL</li>
+ <li>MySQL</li>
+ <li>Oracle</li>
+ <li>POstgres</li>
+ <li>DB2</li>
+ <li>Sybase</li>
+ <li>SQL Server</li>
+ </ul>
+
+ Jetspeed is distributed with the Hypersonic-SQL database
+ configured as the default.
+ </p>
+ <p>
+ The database configuration will be setup during the
+ installation process. If you are not going to use the
+ HSQLDB, you need to install your chosen database package
+ and configure a database user who will own the Jetspeed
+ tables.
+ </p>
+ </section>
+ <section name="3 Servlet Engines">
+ <p>
+ In theory, Jetspeed 2 portals can be run under any
+ servlet container supporting the 2.3 specification or
+ greater. Successful Jetspeed 2 portal applications have
+ been deployed using:
+ <ul>
+ <li>Tomcat 5.5.8 or higher</li>
+ <li>Jetty</li>
+ <li>Websphere</li>
+ <li>Geronimo</li>
+ <li>JBoss</li>
+ </ul>
+ </p>
+ <subsection name=" Tomcat Configuration">
+ <p>
+ Jetspeed 2 can use the Tomcat Manager application
+ for managing portlet applications with the Portlet
+ Application Lifecycle Manager Portlet (PALM). To be
+ able to do so it needs a configured Tomcat user with
+ the predefined 'manager' role in the
+ ${org.apache.jetspeed.server.home}/conf/tomcat-users.xml.
+ </p>
+ <p>
+ A minimal example tomcat-users.xml can look like:
+ <source>
+ <![CDATA[
<tomcat-users>
<role rolename="manager"/>
<user username="j2deployer" password="xxxxx" roles="manager"/>
</tomcat-users>]]>
- </source>
- <i>
- The attribute values for username and password must correspond to the specified values for
- <code>${org.apache.jetspeed.services.autodeployment.user}</code> and
- <code>${org.apache.jetspeed.services.autodeployment.user}</code> as described above.
- </i>
- </p>
- <subsection name="Tomcat 5.5.9 on Windows">
- <p>
- To have redeployment and undeployment working properly when using Tomcat 5.5.9 on Windows you have to set the
- global Context attribute "antiJARLocking" to true.
- </p>
- <p>
- In ${org.apache.jetspeed.server.home}\conf\context.xml use:
- <source>
- <![CDATA[
+ </source>
+ <i>
+ The attribute values for username and password
+ must correspond to the specified values for
+ <code>
+ ${org.apache.jetspeed.services.autodeployment.user}
+ </code>
+ and
+ <code>
+ ${org.apache.jetspeed.services.autodeployment.user}
+ </code>
+ as described above.
+ </i>
+ </p>
+ </subsection>
+ <subsection name="Tomcat 5.5.9 on Windows">
+ <p>
+ To have redeployment and undeployment working
+ properly when using Tomcat 5.5.9 on Windows you have
+ to set the global Context attribute "antiJARLocking"
+ to true.
+ </p>
+ <p>
+ In
+ ${org.apache.jetspeed.server.home}\conf\context.xml
+ use:
+ <source>
+ <![CDATA[
<Context antiJARLocking="true">
...
</Context>]]>
- </source>
- </p>
- </subsection>
- </section>
- <section name="4. Creating a new Portal Application">
- <p>
- Now we're going to configure, setup and build a new custom portal application using the Jetspeed-2 maven-plugin.
- </p>
- <subsection name="4.1 Set the maven remote repository lookup configuration">
- <p>
- To be able to setup a Jetspeed 2 based portal the maven remote repository lookup needs to be configured
- properly in your <code>${USER_HOME}/build.properties</code>:
- <source>
- <![CDATA[
-maven.repo.remote = http://www.bluesunrise.com/maven/, http://www.ibiblio.org/maven/, \
- http://dist.codehaus.org/, http://cvs.apache.org/repository]]>
- </source>
- <i>
- Note: the order in which these repositories must be specified is significant!
- </i>
- </p>
- </subsection>
- <subsection name="4.2 Install the Jetspeed 2 maven-plugin">
- <p>
- The first time, and when you want to upgrade to a newer version of Jetspeed 2, you need to install the
- maven-plugin as follows:
- <source>
- <![CDATA[
-maven -DartifactId=maven-jetspeed2-plugin -DgroupId=jetspeed2 -Dversion=2.0-M4-SNAPSHOT plugin:download]]>
- </source>
- <i>
- Note: you can set the version flag to the specific version you want to install, 2.0-M4-SNAPSHOT is just an
- example here.
- </i>
- </p>
- </subsection>
- <subsection name="4.3 Generate a new portal project">
- <p>
- Once you have the maven-plugin installed and set properties as needed, generate a default portal configuration
- using the plugin as follows:
- <source>
- <![CDATA[
-maven j2:portal.genapp]]>
- </source>
- <i>
- This maven goal actually executes several subgoals which are further described in the
- <a href="j2-maven-plugin.html">maven-plugin documentation</a> itself.
- </i>
- </p>
- </subsection>
- <subsection name="4.4 Further customization of the portal">
- <p>
- This section doesn't specify anything to do. After the portal project is generated you can adapt and customize
- it to your taste by overriding and merging your own configurations and extensions.
- </p>
- <p>
- You can regenerate or update (part of) your portal project with the <code>j2:portal.genapp</code> goal as
- described in the previous section or use its subgoals directly.
- </p>
- </subsection>
- <subsection name="4.5 Build the portal">
- <p>
- Once your portal configuration and setup is ready, you can build and install the portal application in your
- local maven repository (as needed for deployment) using the following standard maven goal from your custom
- portal project directory (in ${org.apache.jetspeed.portal.home}):
- <source>
- <![CDATA[
-maven war:install]]>
- </source>
- </p>
- <p>
- You are now ready to deploy the new portal application. For this, skip the following section on building the
- Jetspeed 2 portal from source and continue with the <a href="#6__Deploy_and_Run">deployment</a> section.
- </p>
- </subsection>
- </section>
- <section name='5. Build Jetspeed 2 from source'>
- <p>
- Build the Jetspeed 2 portal directly from the source is somewhat easier to do but should only be done if you
- don't want to create a new, customizable portal.
- </p>
- <subsection name="5.1 Setup the Jetspeed 2 source and build properties">
- <p>
- The Jetspeed 2 source contains a <code>project.properties</code> file which provides all of the required
- portal configuration settings as described <a href="#Required_Portal_Configuration_Properties">above</a>.
- </p>
- <p>
- You should <i><b>not</b></i> define any of those properties in your <code>${USER_HOME}/build.properties</code>.
- <br />
- Instead, you <i>must</i> set a <code>org.apache.jetspeed.project.home</code> property, specifying the location
- where you expanded the downloaded source or checked out the source from subversion, like:
- <source>
- <![CDATA[
-# required Jetspeed 2 portal configuration property for building from the source
-org.apache.jetspeed.project.home = /home/apache/jetspeed-2/]]>
- </source>
- <i>
- Note: you still need to specify the required application server properties as described
- <a href="#Required_Application_Server_Properties">above</a>.
- </i>
- </p>
- <p>
- The Jetspeed 2 project.properties uses this property to define the required
- <code>org.apache.portal.home</code>:
- <source>
- <![CDATA[
-org.apache.jetspeed.portal.home = ${org.apache.jetspeed.project.home}]]>
- </source>
- So, they are the same when you build the Jetspeed 2 portal from the source.
- </p>
- <p>
- When you are going to deploy the portal as described further below, you'll see references to the
- <code>org.apache.jetspeed.portal.home</code> which you can translate with the root folder of your Jetspeed 2
- source.
- </p>
- <p>
- If you want to run the testcases when building the Jetspeed 2 sources <i>and</i> don't want to use the default
- HSQLDB test database, you need to override the default test database properties, similar to the production
- database properties as described <a href="#Optional_Database_Server_Properties">above</a>:
- <ul>
- <li><code>org.apache.jetspeed.test.database.default.name</code></li>
- <li><code>org.apache.jetspeed.test.database.url</code></li>
- <li><code>org.apache.jetspeed.test.database.user</code></li>
- <li><code>org.apache.jetspeed.test.database.password</code></li>
- <li><code>org.apache.jetspeed.test.database.driver</code></li>
- <li><code>org.apache.jetspeed.test.database.drivers.path</code></li>
- </ul>
- <i>
- Note: due to outstanding issue <a href="http://issues.apache.org/jira/browse/JS2-320">JS2-320</a> you
- currently <b>must</b> use hard coded values for the test database properties.
- </i>
- </p>
- </subsection>
- <subsection name="Initialize the maven-plugin">
- <p>
- Instead of downloading and installing the Jetspeed 2 maven-plugin, you are going to build and install it
- directly from the source. You will need to repeat this every time you update to a newer version of Jetspeed 2
- or change its project configuration, the plugin itself or the resources used by the plugin.
- </p>
- <p>
- Build and install the maven-plugin as follows from the root directory of the Jetspeed-2 source:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.project.home}
-maven initMavenPlugin]]>
- </source>
- </p>
- </subsection>
- <subsection name="Optional: start the HSQLDB test database first">
- <p>
- If you are going to run the testcases and are using the default HSQLDB database configuration, you will need
- to start the test database before building Jetspeed 2 in a <i>separate</i> console:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.project.home}
-maven j2:start.test.server]]>
- </source>
- </p>
- <p>
- After the build is finished you can stop the database and close this console with a <code>Ctrl-C</code>.
- </p>
- </subsection>
- <subsection name="Build the Jetspeed 2 portal and demo portlet applications">
- <p>
- For a full build and installation of the portal and the demo portlet applications in your local maven
- repository run:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.project.home}
-maven allClean allBuild]]>
- </source>
- </p>
- <p>
- But, if you also want to run the testcases during the build run the following instead:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.project.home}
-maven -Dmaven.test.skip=false allClean allBuild]]>
- </source>
- </p>
- <p>
- You are now ready to deploy the Jetspeed 2 Portal.
- </p>
- </subsection>
- </section>
- <section name="6. Deploy and Run">
- <subsection name="Optional: start the HSQLDB production database first">
- <p>
- If you are using the default HSQLDB database you need to start it before deploying the portal.
- </p>
- <p>
- To start the HSQLDB production database run the following in a <i>separate</i> console:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.portal.home}
-maven j2:start.production.server]]>
- </source>
- </p>
- <p>
- You need to have this database running during the deployment and while running the application server.
- Afterwards you can stop the database and close this console with a <code>Ctrl-C</code>.
- </p>
- <p>
- Note: this is required when using the <code>j2:quickStart</code> goal as described below. The Jetspeed 2
- maven-plugin provides other (sub)goals which you can use without (re)creating a production database and/or
- inserting default portal configuration data. See the <a href="j2-maven-plugin.html">Plugin documentation</a>
- for further information about the available goals.
- </p>
- </subsection>
- <subsection name="Deploy">
- <p>
- We currently only cover deploying to Tomcat 5 or Tomcat 5.5.
- </p>
- <p>
- Information about deployment to other application servers can be found at the The Jetspeed 2
- <a href="http://wiki.apache.org/portals/Jetspeed2">Wiki</a>.
- </p>
- <p>
- To deploy a default Jetspeed 2 portal, including the demo portlet applications, run the following in a
- <i>separate</i> console:
- <source>
- <![CDATA[
-cd ${org.apache.jetspeed.portal.home}
-maven j2:quickStart]]>
- </source>
- <i>
- Note: the <a href="j2-maven-plugin.html">maven-plugin documentation</a> described other goals you can use to
- customize the deployment to your taste.
- </i>
- </p>
- </subsection>
- <subsection name="Run">
- <p>
- The final step is starting up your Tomcat server and the portal will automatically install any deployed
- portlet applications.
- </p>
- <p>
- Then you can access the portal with your browser at:
- <pre>
- <a href="http://localhost:8080/jetspeed">http://localhost:8080/jetspeed</a>
- </pre>
- or replace "jetspeed" in the above url with the name of you own portal application
- (<code>${org.apache.jetspeed.portal.artifactId}</code>).
- </p>
- </subsection>
- <subsection name="Default installed user accounts">
- <p>
- With the default Jetspeed 2 portal deployment, several example user accounts are inserted into the portal
- database with which you can logon to the portal:
- <table>
- <tr>
- <th>username</th>
- <th>password</th>
- <th>roles</th>
- </tr>
- <tr>
- <td><code>admin</code></td>
- <td><code>admin</code></td>
- <td><code>admin, manager, user</code></td>
- </tr>
- <tr>
- <td><code>manager</code></td>
- <td><code>manager</code></td>
- <td><code>manager, user</code></td>
- </tr>
- <tr>
- <td><code>jetspeed</code></td>
- <td><code>jetspeed</code></td>
- <td><code>manager</code></td>
- </tr>
- <tr>
- <td><code>user</code></td>
- <td><code>user</code></td>
- <td><code>user</code></td>
- </tr>
- <tr>
- <td><code>tomcat</code></td>
- <td><code>tomcat</code></td>
- <td></td>
- </tr>
- </table>
- </p>
- </subsection>
- </section>
- </body>
+ </source>
+ </p>
+ </subsection>
+ <subsection
+ name="Jetty - A Quick Test Environment or a Production Servlet Container">
+ Jetty can be used for a production deployment but it is
+ most commonly used to quickly test customizations
+ without interfering with the production servlet
+ container. It does not require any special
+ configuration.
+ </subsection>
+ </section>
+ <section
+ name='4. Installing Jetspeed from Source or Binary Distributions'>
+ <p>
+ Depending on what you want to do, you have the choice of
+ installing Jetspeed from a binary release or from the
+ sources. If you want to modify the core functionality of
+ Jetspeed or contribute to the development of Jetspeed,
+ you need to work with the sources. If you are only
+ interested in building your own custom enterprise
+ portal, you can start with a binary release of Jetspeed.
+ </p>
+ <p>
+ If you start with the binary distribution, you can
+ switch to the source distribution later. Using the
+ binary distribution route, you will not have access to
+ certain functions, including:
+ <ul>
+ <li>DST ???</li>
+ <li>DST ???</li>
+ </ul>
+ Most people should start with the binary distribution.
+ </p>
+ </section>
+ <section name='5. Jetspeed build'>
+ <p>
+ Your installation instructions will depend on whether
+ you are
+ <a href="getting-started-source.html">
+ building from source
+ </a>
+ or
+ <a href="getting-started-binary.html">
+ building from a binary distribution
+ </a>
+ .
+ </p>
+ </section>
+ </body>
</document>
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-app-servers.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-app-servers.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-app-servers.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-app-servers.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,245 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Jetspeed 2 Database Configuration</title>
+ <subtitle>Welcome to Jetspeed 2</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org" />
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ <person name="Ron Wheeler"
+ email="rwheeler@artifact-software.com" />
+
+ </authors>
+ </properties>
+ <body>
+ <section name="Application Server Properties">
+ <p>
+ <i>
+ Note: The maven-plugin currently only supports the
+ Tomcat Server 5.0.x or 5.5.x
+ </i>
+ </p>
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th nowrap="nowrap">Default value</th>
+ </tr>
+ <tr>
+ <td>
+ <code>org.apache.jetspeed.server.home</code>
+ </td>
+ <td>
+ The root folder of your Tomcat server
+ installation.
+ <br />
+ Example:
+ <code>${CATALINA_HOME}/</code>
+ .
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>org.apache.jetspeed.server.shared</code>
+ </td>
+ <td>
+ The location of the shared jars in your Tomcat
+ installation.
+ <br />
+ Example:
+ <code>
+ ${org.apache.jetspeed.server.home}/shared/lib/
+ </code>
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>org.apache.jetspeed.deploy.war.dir</code>
+ </td>
+ <td>
+ The location of web applications in your Tomcat
+ installation.
+ <br />
+ Example:
+ <code>
+ ${org.apache.jetspeed.server.home}/webapps/
+ </code>
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.services.autodeployment.user
+ </code>
+ </td>
+ <td>
+ A Tomcat user with the manager role.
+ <br />
+ Used to access the Tomcat Manager application
+ from within the portal, explained below.
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.services.autodeployment.password
+ </code>
+ </td>
+ <td>
+ The password of the Tomcat user above.
+ <br />
+ Used to access the Tomcat Manager application
+ from within the portal, explained below.
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.catalina.version.major
+ </code>
+ </td>
+ <td>
+ The major version of the Tomcat server you are
+ using: 5 or 5.5
+ <br />
+ Example:
+ <code>5.5</code>
+ </td>
+ <td>
+ <i>no default</i>
+ </td>
+ </tr>
+ </table>
+ </section>
+ <section name="Optional Database Server Properties">
+ <p>
+ Jetspeed-2 and its maven-plugin uses, as well as
+ provides, by default a HSQLDB database.
+ </p>
+ <p>
+ If you want to use a different database you will need to
+ override the following properties:
+ </p>
+ <table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ <th nowrap="nowrap">Default value</th>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.database.default.name
+ </code>
+ </td>
+ <td>
+ The type of database you are using. Used for sql
+ script generation with Torque.
+ <br />
+ Currently supported databases (with
+ corresponding Torque target database name):
+ <ul>
+ <li>hsql (hypersonic)</li>
+ <li>oracle (oracle)</li>
+ <li>mysql (mysql)</li>
+ <li>postgres (postresql)</li>
+ <li>mssql (mssql)</li>
+ </ul>
+ </td>
+ <td>hsql</td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.database.url
+ </code>
+ </td>
+ <td>The jdbc connection url</td>
+ <td>jdbc:hsqldb:hsql://127.0.0.1:9001</td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.database.user
+ </code>
+ </td>
+ <td>The database user name to connect with.</td>
+ <td>sa</td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.database.password
+ </code>
+ </td>
+ <td>
+ The database user its password to connect with.
+ </td>
+ <td>
+ <i>empty</i>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.database.driver
+ </code>
+ </td>
+ <td>The jdbc driver class name</td>
+ <td>org.hsqldb.jdbcDriver</td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ org.apache.jetspeed.production.jdbc.drivers.path
+ </code>
+ </td>
+ <td>
+ A Java classpath style path to the jdbc driver
+ classes or jar(s) needed for connecting to the
+ database.
+ <br />
+ Example:
+ <code>
+ /lib/ojdbc14.jar;/lib/nls_charset12.jar
+ </code>
+ </td>
+ <td>
+ <i>empty</i>
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-components.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-components.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-components.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-components.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Guide to Jetspeed-2 Component Architecture</title>
+ <subtitle>Guide to Jetspeed-2 Component Architecture</subtitle>
+ <authors>
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Guide to Jetspeed-2 Component Architecture">
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-database.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-database.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-database.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-database.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,219 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Jetspeed 2 Database Configuration</title>
+ <subtitle>Welcome to Jetspeed 2</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org" />
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ <person name="Ron Wheeler"
+ email="rwheeler@artifact-software.com" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Default Database">
+ <p>
+ The default database distributed with Jetspeed-2 is the
+ Hypersonic SQL Java Database (HSQL). HSQL runs in its
+ own process outside of Jetspeed-2. It is not a
+ production-ready database, however it allows you to get
+ up and running quickly. To move on to a more robust
+ database, follow the instructions in the next section.
+ </p>
+ </section>
+ <section name="MySQL">
+ <p>
+ To run with My SQL, add the following properties to your
+ $HOME/build.properties:
+ </p>
+ <source test="">
+ <![CDATA[
+
+# -------------------------------------------------------------------------
+# configure MySQL Test DB (only needed when running unit tests)
+# -------------------------------------------------------------------------
+org.apache.jetspeed.test.database.default.name=mysql
+org.apache.jetspeed.test.database.url = jdbc:mysql://j2-server/j2test
+org.apache.jetspeed.test.database.driver = com.mysql.jdbc.Driver
+org.apache.jetspeed.test.database.user = jetspeed2
+org.apache.jetspeed.test.database.password = whatever
+# -------------------------------------------------------------------------
+# configure MySQL Production DB
+# -------------------------------------------------------------------------
+org.apache.jetspeed.production.database.default.name=mysql
+org.apache.jetspeed.production.database.url = jdbc:mysql://j2-server/j2
+org.apache.jetspeed.production.database.driver = com.mysql.jdbc.Driver
+org.apache.jetspeed.production.database.user = jetspeed2
+org.apache.jetspeed.production.database.password = whatever
+# -------------------------------------------------------------------------
+
+]]>
+ </source>
+ <p>
+ In the example above, you will need to have a MySQL
+ server running on a host named 'j2-server' with a
+ database called 'j2' for production.
+ <br />
+ If you are going to run the unit tests you will also
+ need an additional test database called 'j2test'.
+ <br />
+ A user named 'jetspeed2' should be granted access to
+ both the 'j2' and 'j2test' databases.
+ </p>
+
+ <subsection name="MySQL Known Issues">
+ <p>None</p>
+ </subsection>
+
+ </section>
+
+ <section name="Oracle">
+ <p>
+ To run with Oracle, add the following properties to your
+ $HOME/build.properties:
+ </p>
+
+ <source test="">
+ <![CDATA[
+
+# -------------------------------------------------------------------------
+# configure Oracle Test DB (only needed when running unit tests)
+# -------------------------------------------------------------------------
+# org.apache.jetspeed.test.database.default.name=oracle
+# org.apache.jetspeed.test.database.ojb.platform=oracle9i
+# org.apache.jetspeed.test.database.url = jdbc:oracle:thin:@j2-sever:1521:j2db
+# org.apache.jetspeed.test.database.driver = oracle.jdbc.driver.OracleDriver
+# org.apache.jetspeed.test.database.user = j2test
+# org.apache.jetspeed.test.database.password = whatever
+# -------------------------------------------------------------------------
+# configure Oracle Production DB
+# -------------------------------------------------------------------------
+# org.apache.jetspeed.production.database.default.name=oracle
+# org.apache.jetspeed.production.database.ojb.platform=oracle9i
+# org.apache.jetspeed.production.database.url = jdbc:oracle:thin:@j2-server:1521:j2db
+# org.apache.jetspeed.production.database.driver = oracle.jdbc.driver.OracleDriver
+# org.apache.jetspeed.production.database.user = j2
+# org.apache.jetspeed.production.database.password = whatever
+# -------------------------------------------------------------------------
+
+]]>
+ </source>
+ <p>
+ In the example above, you will need to have a Oracle
+ server running on a host named 'j2-server' and have an
+ Oracle database SID named 'j2db' installed on that
+ server. Also, you will need a database user (schema)
+ called 'j2' for production usage.
+ <br />
+ If you are going to run the unit tests you will need an
+ additional user called 'j2test'.
+ </p>
+
+ <subsection name="Oracle Known Issues">
+ <p>
+ Only for the first time you create the database for
+ Oracle, there is an issue with the drop statements.
+ To get around this problem, set your properties as
+ above in your $HOME/build.properties, and then run
+ these commands using the
+ <a href="j2-maven-plugin.html">
+ Jetspeed 2 Maven plugin
+ </a>
+ :
+ </p>
+ <source test="">
+ <![CDATA[
+
+maven j2:db.scripts.gen
+maven j2:dropdrops
+maven j2:db.create.test (only when running unit tests)
+maven j2:db.create.production
+
+]]>
+ </source>
+ </subsection>
+
+ </section>
+
+ <section name="Drivers">
+ <p>
+ JDBC drivers are configured to work with the Maven build
+ by adding your specified JDBC driver jars to the Maven
+ class path. Specify the jars with the
+ <b>org.apache.jetspeed.test.jdbc.drivers.path</b>
+ and
+ <b>org.apache.jetspeed.production.jdbc.drivers.path</b>
+ properties in your $HOME/build.properties.
+ </p>
+ <p>
+ NOTE: The Hypersonic JDBC driver is distributed with
+ Jetspeed and require no configuration.
+ </p>
+ <source test="">
+ <![CDATA[
+
+# My SQL Driver Path Example, test and production
+org.apache.jetspeed.test.jdbc.drivers.path=
+ /Portal/lib/MySQL/mysql-connector-java-3.0.8-stable-bin.jar
+org.apache.jetspeed.production.jdbc.drivers.path=
+ /Portal/lib/MySQL/mysql-connector-java-3.0.8-stable-bin.jar
+
+# Oracle 9i Driver Path Example, test and production
+org.apache.jetspeed.test.jdbc.drivers.path=
+ /Portal/lib/oracle/ojdbc14.jar;/Portal/lib/oracle/nls_charset12.jar
+org.apache.jetspeed.production.jdbc.drivers.path=
+ /Portal/lib/oracle/ojdbc14.jar;/Portal/lib/oracle/nls_charset12.jar
+
+# Oracle 8i Driver Path Example, test and production
+org.apache.jetspeed.test.jdbc.drivers.path=
+ /Portal/lib/oracle/classes12.jar;
+org.apache.jetspeed.production.jdbc.drivers.path=
+ /Portal/lib/oracle/classes12.jar;
+
+]]>
+ </source>
+
+ <subsection name="Distributing Drivers">
+ <p>
+ When Jetspeed is deployed to an application server
+ using the maven deploy target, only the Hypersonic
+ JDBC driver is copied into the web application. To
+ distribute a specific driver (i.e. Oracle, MySQL),
+ you will need to copy the driver into the
+ application server's common class path for shared
+ code.
+ </p>
+ <table>
+ <tr>
+ <th>Application Server</th>
+ <th>Procedure</th>
+ </tr>
+ <tr>
+ <td>Tomcat 5 and 5.5</td>
+ <td>
+ copy driver(s) to ${TOMCAT_HOME}/endorsed/
+ </td>
+ </tr>
+
+ </table>
+
+ </subsection>
+
+ </section>
+ </body>
+</document>
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,93 @@
+<?xml version="1.0"?>
+<!--
+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.
+-->
+<document>
+ <properties>
+ <title>Guide to Jetspeed Decoration</title>
+ <subtitle>Documentation for Designers working with Jetspeed Decorations</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Introduction to Decorators">
+<p>
+Decorators are defined as any static or semi-static markup surrounding a dynamically generated Fragment.
+Decorators are usually written with either Velocity or JSP templates.
+Decorators define how a single portal page is aggregated. A layout is made up of:
+<ul>
+ <li>One or more templates</li>
+ <li>A template descriptor</li>
+ <li>Images</li>
+ <li>A Stylesheet (CSS)</li>
+ <li>Macros</li>
+</ul>
+</p>
+<p>
+ <img src='images/layouts/layouts-overview.png'/>
+</p>
+</section>
+<section name='Packaging'>
+<p>
+Layouts are packaged in a JAR file. Supported decorators:
+<ul>
+ <li>Page Decorators</li>
+ <li>Portlet Decorators</li>
+ <li>Generic Decorators</li>
+ <li>Localized Decorators</li>
+</ul>
+Operations Supported:
+<ul>
+ <li>Deploy</li>
+ <li>Un-deploy</li>
+ <li>Re-deploy</li>
+</ul>
+The decorator.properties file must be located in the root directory of the jar archive and
+contain the properties outlined in the next slide to be identified as a decorator by the auto
+deployment system. The deployer will relocate the locale specific content to satisfy J2
+content locators as necessary on deploy and undeploy. The current implementation supports
+only 2 character language and country codes.
+</p>
+</section>
+<section name='Decorator Properties'>
+<p>
+The decorator.properties file must be located in the root directory of the jar archive and
+contain the properties outlined above to be identified as a decorator by the auto-deployment system.
+</p>
+<p>
+A deployable decorator must have the following properties set or defaulted in the decorator.properties
+configuration:
+
+<source test=""><![CDATA[
+
+id = IDENTIFIER
+media.type= HTML | WML
+decorates = layout | portlet | any
+
+]]></source>
+
+To avoid conflicts with the locale logic and runtime locators, decorators should be
+named with ids longer than 2 characters in length. The media.type property defaults to 'html'.
+The 'any' value for the decorates property is mapped to the generic deployment directory.
+The deployer will relocate the locale specific content to satisfy J2 content locators as
+necessary on deploy and undeploy. The current implementation supports only 2
+character language and country codes.
+</p>
+</section>
+
+</body>
+</document>
+
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-dir-structure.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-dir-structure.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-dir-structure.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-dir-structure.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Guide to Jetspeed-2 Component Architecture</title>
+ <subtitle>Guide to Jetspeed-2 Component Architecture</subtitle>
+ <authors>
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Guide to Jetspeed-2 Component Architecture">
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-jpt.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-jpt.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-jpt.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-jpt.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,167 @@
+<?xml version="1.0"?>
+<!--
+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.
+-->
+<document>
+ <properties>
+ <title>Guide to Jetspeed Power Tool</title>
+ <subtitle>Documentation for Designers working with the Jetspeed Power Tool.</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Jetspeed Power Tool">
+<p>
+The Jetspeed Power Tool (JPT) is a velocity tool used in Layouts and Decorators to generate dynamic content.
+The JPT is a request level velocity tool, and is available to all layouts and decorators.
+The JPT is referenced in your decorator or layout as:
+<source test=""><![CDATA[
+$jetspeed
+]]></source>
+All public JPT APIs can be accessed with:
+<ul>
+ <li>Java dot notation for methods</li>
+ <li>JavaBean shortcuts for properties (getter/setter)</li>
+</ul>
+Example of calling a method:
+<source test=""><![CDATA[
+# call a method 'getTitle' with 2 parameters
+$jetspeed.getTitle($myPE, $myF)
+]]></source>
+Example of calling getting a property:
+<source test=""><![CDATA[
+# get the page bean, equivalent to $jetspeed.getPage()
+$jetspeed.page
+]]></source>
+</p>
+</section>
+<section name="JPT Velocity API">
+<p>The table below defines the Jetspeed Power Tool API for Velocity</p>
+<hr/>
+<table>
+ <tr>
+ <th>API</th>
+ <th><b>decorateAndInclude($fragment)</b></th>
+ </tr>
+ <tr>
+ <td>Description</td>
+ <td>
+ Retrieves the application relative path to a decorator template for a given
+ fragment parameter <b>($fragment)</b> to be included by Velocity.
+ Should be passed as a parameter to the Velocity #parse function (#parse includes
+ another Velocity template).
+ </td>
+ </tr>
+ <tr>
+ <td>Parameter</td>
+ <td><b>$fragment</b> - the fragment to be included and decorated.</td>
+ </tr>
+ <tr>
+ <td>Returns</td>
+ <td><b>String</b> - Application relative path to a decorator template.</td>
+ </tr>
+ <tr>
+ <td>Examples</td>
+ <td>#parse($jetspeed.decorateAndInclude($fragment))<br/>returns<br/>/WEB-INF/decorations/layout/html/tigris/decorator-top.vm</td>
+ </tr>
+</table>
+<hr/>
+<table>
+ <tr>
+ <th>API</th>
+ <th><b>getAbsoluteUrl(appRelativePath)</b></th>
+ </tr>
+ <tr>
+ <td>Description</td>
+ <td>
+ Given a relative path to an portlet application resource, returns an absolute URL.
+ This API should not be used to reference template ULS since they are usually inaccessible
+ as absolute URLs because they are often located in a CMS or behind the secured WEB-INF directory.
+ </td>
+ </tr>
+ <tr>
+ <td>Parameter</td>
+ <td><b>relativePath</b> - a relative path to a resource in the decorator package.</td>
+ </tr>
+ <tr>
+ <td>Returns</td>
+ <td><b>String</b> - The full absolute path to a web resource</td>
+ </tr>
+ <tr>
+ <td>Examples</td>
+ <td>$jetspeed.getAbsoluteUrl("/images/test.gif")<br/>returns<br/>http://localhost:8080/jetspeed/portal/images/test.gif</td>
+ </tr>
+</table>
+<hr/>
+<table>
+ <tr>
+ <th>API</th>
+ <th><b>columns</b></th>
+ </tr>
+ <tr>
+ <td>Description</td>
+ <td>
+ Returns a list of column for the current fragment during a layout aggregation.
+ </td>
+ </tr>
+ <tr>
+ <td>Parameter</td>
+ <td><b>-</b></td>
+ </tr>
+ <tr>
+ <td>Returns</td>
+ <td><b>List</b> - a standard Java List of sub-fragments or portlets</td>
+ </tr>
+ <tr>
+ <td>Examples</td>
+ <td>#set ($table = $jetspeed.columns)<br/>#foreach($entry in $table)
+ </td>
+ </tr>
+</table>
+<hr/>
+<table>
+ <tr>
+ <th>API</th>
+ <th><b></b></th>
+ </tr>
+ <tr>
+ <td>Description</td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td>Parameter</td>
+ <td><b></b></td>
+ </tr>
+ <tr>
+ <td>Returns</td>
+ <td><b></b></td>
+ </tr>
+ <tr>
+ <td>Examples</td>
+ <td></td>
+ </tr>
+</table>
+<hr/>
+
+<p>
+<i>Documentation for Jetspeed 2.0-M2 release.</i>.
+</p>
+</section>
+
+</body>
+</document>
+
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-l10n.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-l10n.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-l10n.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-l10n.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,87 @@
+<?xml version="1.0"?>
+<!--
+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.
+-->
+<document>
+ <properties>
+ <title>Guide to Localization for Jetspeed 2</title>
+ <subtitle>Jetspeed 2 Localization for your language</subtitle>
+ <authors>
+ <person name="Shinsuke Sugaya" email="shinsuke@yahoo.co.jp"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Translate Messages">
+<p>
+Jetspeed2 has the translatable messages in Java properties and XML files
+</p>
+<subsection name="Properties File">
+<p>
+This document shows how to create a message properties file for your language.
+</p>
+<h5>1. Find <code>*_en.properties</code></h5>
+<p>
+<code>*_en.properties</code> is English message properties file. You can use it as a base properties file for your language.
+</p>
+<p>
+If you use UNIX system, you can use <code>find</code> command to find the properties files:
+</p>
+<source test=""><![CDATA[
+$ cd ${jetspeed-2-home}
+$ find . -type f | grep -v CVS | grep _en.properties
+]]></source>
+<h5>2. Copy <code>*_en.properties</code> to <code>*_<your language, [country and variant]>.properties.orig</code></h5>
+<p>
+To translate messages, copy the properties file for your language. For more information about Language, Country and Variant code, see "<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Locale.html">JavaDoc: Locale Class</a>", "<a href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO Language Code</a>" and "<a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">ISO Country Code</a>".
+</p>
+<p>
+Example:
+</p>
+<source test=""><![CDATA[
+$ cd applications/localeselector/src/java/org/apache/jetspeed/portlets/localeselector/resources/
+$ cp LocaleSelectorResources_en.properties LocaleSelectorResources_ja.properties.orig
+]]></source>
+<p>
+where <code>*_ja.properties</code> is Japanese message file.
+</p>
+<h5>3. Translate *_<your language, [country and variant]>.properties.orig in your language</h5>
+<p>
+For more information about a properties file, see "<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)">JavaDoc: Properties Class</a>".
+</p>
+<h5>4. Run <code>native2ascii</code> command</h5>
+<p>
+Since the properties file is assumed to be using the ISO 8859-1 character encoding, use <code>native2ascii</code> command to convert to ISO 8859-1. For more information about "<a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/native2ascii.html">native2ascii(Solaris)</a>" or "<a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/native2ascii.html">native2ascii(Windows)</a>".
+</p>
+<p>
+Example:
+</p>
+<source test=""><![CDATA[
+$ native2ascii LocaleSelectorResources_ja.properties.orig LocaleSelectorResources_ja.properties
+]]></source>
+<h5>5. Build & Deploy Jetspeed2, and see if your translation is displayed</h5>
+<p>
+For more information about Jetspeed 2 build and deploy steps, see "<a href="getting-started.html">Getting Started</a>".
+</p>
+<h5>6. Create a new JIRA issue, and attach <code>*_<your language, [country and variant]>.properties</code></h5>
+<p>
+JIRA site for Jetspeed 2 is <a href="http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10492">http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10492</a>. To create a new JIRA issue, go to "CREATE NEW ISSUE"(select "l10n" as Component/s name).
+</p>
+
+</subsection>
+</section>
+
+</body>
+</document>
+
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-layouts.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-layouts.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-layouts.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-layouts.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,150 @@
+<?xml version="1.0"?>
+<!--
+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.
+-->
+<document>
+ <properties>
+ <title>Layouts and Decorations</title>
+ <subtitle>Documentation for Designers working with Jetspeed Layouts and Decorations</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Layouts">
+<p>
+Layout templates are packaged in special Jetspeed-specific and deployable portlet applications.
+Layout templates control the overall aggregation of a portal page. Layout templates are
+combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
+of the box with several layout components including one, two and three column layouts.
+See the <a href='#Jetspeed-2 Layouts'>Jetspeed-2 Layouts</a> below for all available Layouts in the
+default Jetspeed-2 system. Of course you can define and derive your own layouts.
+</p>
+<p>
+With regards to aggregation, layouts define how a single portal page is aggregated.
+A l ayout defines the fashion in which grouping of fragments
+will organized relative to the final, aggregated
+content of a request to the portal. Layouts are defined by
+a portlet which applies an algorithm to a template to
+generate the aggregated content of a page. Typical
+algorithms are two column, three column, nested.
+</p>
+<p>A layout is made up of:
+<ul>
+ <li>One or more templates</li>
+ <li>A template descriptor</li>
+ <li>Images</li>
+ <li>A Stylesheet (CSS)</li>
+ <li>Macros</li>
+</ul>
+</p>
+<p>
+ <img src='images/layouts/layouts-overview.png'/>
+</p>
+</section>
+<section name="Layouts Packaging">
+<p>
+Layouts are packaged as standard portlet applications.
+Layouts usual have a
+</p>
+<p>
+Operations Supported:
+<ul>
+ <li>Deploy</li>
+ <li>Un-deploy</li>
+ <li>Re-deploy</li>
+</ul>
+</p>
+</section>
+<section name='Jetspeed-2 Layouts'>
+<p>
+Jetspeed-2 comes out of the box with several layout components including one, two and three
+column layouts. Of course you can define and derive your own layouts. The table below lists
+the available layout components in Jetspeed version 2.0. When customizing (editing) a page,
+the layout component is selected. One layout may be assigned per PSML page.
+</p>
+<table>
+ <tr>
+ <th>Layout</th>
+ <th>Type</th>
+ <th>Columns</th>
+ <th>Sizes</th>
+ <th>Modes</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>VelocityOneColumn</b></td>
+ <td>OneColumn</td>
+ <td>1</td>
+ <td>100%</td>
+ <td>view,edit,help</td>
+ <td>A single column display of one or more fragments taking up 100% of the portlet display area.</td>
+ </tr>
+ <tr>
+ <td><b>VelocityTwoColumns</b></td>
+ <td>TwoColumns</td>
+ <td>2</td>
+ <td>50%,50%</td>
+ <td>view,edit,help</td>
+ <td>A two column display of one or more fragments where each column is allocated to 50% respectively of the portlet display area.
+ Fragments may be placed in either column using <a href='psml.html'>PSML</a> fragment definitions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>VelocityTwoColumns</b></td>
+ <td>TwoColumns</td>
+ <td>2</td>
+ <td>50%,50%</td>
+ <td>view,edit,help</td>
+ <td>A two column display of one or more fragments where each column is allocated to 50% of the portlet display area respectively.
+ Fragments may be placed in either column using <a href='psml.html'>PSML</a> fragment definitions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>VelocityTwoColumnsSmallLeft</b></td>
+ <td>TwoColumns</td>
+ <td>2</td>
+ <td>15%,85%</td>
+ <td>view,edit,help</td>
+ <td>A two column display of one or more fragments where the left column is allocated to 15% of the portlet display area,
+ and the right column is allocated to 85% of the portlet display area.
+ Fragments may be placed in either column using <a href='psml.html'>PSML</a> fragment definitions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>VelocityThreeColumns</b></td>
+ <td>ThreeColumns</td>
+ <td>3</td>
+ <td>33%,33%,33%</td>
+ <td>view,edit,help</td>
+ <td>A three column display of one or more fragments where each column is allocated to 33% of the portlet display area respectively.
+ Fragments may be placed in either column using <a href='psml.html'>PSML</a> fragment definitions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>VelocityOneColumnNoActions,<br/>VelocityTwoColumnsNoActions,<br/>VelocityThreeColumnsNoActions</b></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>view</td>
+ <td>Same parameters as their counterparts with actions, but no decorator actions are displayed.
+ </td>
+ </tr>
+</table>
+</section>
+
+</body>
+</document>
+
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-portal-assembly.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-portal-assembly.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-portal-assembly.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-portal-assembly.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Jetspeed 2 Home Page</title>
+ <subtitle>Welcome to Jetspeed 2</subtitle>
+ <authors>
+ <person name="David Le Strat" email="dlestrat@apache.org" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Welcome to Jetspeed-2">
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml?rev=348039&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml Mon Nov 21 16:10:44 2005
@@ -0,0 +1,176 @@
+<?xml version="1.0"?>
+<!--
+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.
+-->
+<document>
+ <properties>
+ <title>Guide to Portal Design</title>
+ <subtitle>Documentation for Designers working with Jetspeed Portal Design</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Portal Design Introduction">
+<p>
+The Java Portlet API (JSR-168) defines the Java standard interface for programming portlets.
+The Java Portlet API specification enables interoperability between Portlets and Portals.
+It is the standard specification for developing Java portlets. However the Java Portlet API
+does not define standards for laying out and aggregating portlets and markup on a page.
+The documentation here under "Portal Design" covers:
+<ul>
+ <li><a href='psml.html'>Page Aggregation - see the section on PSML</a></li>
+ <li><a href='decorators.html'>Page and Portlet Decorators</a></li>
+ <li><a href='layouts.html'>Page Layouts</a></li>
+ <li><a href='jpt.html'>The Jetspeed Power Tool</a></li>
+ <li><a href='site.html'>The Site Content Model</a></li>
+ <li><a href='#Template Locators'>Template Locators</a></li>
+ <li><a href='#Terminology'>Terminology</a></li>
+</ul>
+</p>
+</section>
+<section name='Templates'>
+<p>
+Rendering one or more portlets into a portlet page is largely made up of the process of aggregating
+portlets as dynamic content with templates. Jetspeed-2 makes use of Velocity templates in
+creating a page layout. Although the Jetspeed-2 architecture fully supports the use of JSP templates for
+decorators and layouts, the developers thus far have chosen Velocity as the tool of choice for writing
+templates. There are two types of templates in Jetspeed: layouts and decorators.
+The process of rendering a page is the combined aggregation of a layout template,
+a page decorator template, a PSML definition, and one or more portlet decorator templates.
+As of release 2.0, templates can be stored on the file system. In future releases, templates
+will also be stored in a CMS backend for versioning.
+</p>
+<subsection name='Layout Templates'>
+<p>
+Layout templates are packaged in special Jetspeed-specific and deployable portlet applications.
+Layout templates control the overall aggregation of a portal page. Layout templates are
+combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
+of the box with several layout components including one, two and three column layouts.
+See the <a href='layouts.html'>Layout Documentation</a> for all available Layouts in the
+default Jetspeed-2 system. Of course you can define and derive your own layouts.
+</p>
+</subsection>
+<subsection name='Decorators'>
+ <p>
+Decorator templates are packaged in special Jetspeed-specific and deployable archives.
+Layout templates control the overall aggregation of a portal page. Layout templates are
+combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
+of the box with several layout components including one, two and three column layouts.
+See the <a href='guide-decorators.html'>Decorator Documentation</a> for all available Layouts in the
+default Jetspeed-2 system. Of course you can define and derive your own layouts.
+</p>
+</subsection>
+</section>
+<section name='Template Locators'>
+<p>
+Templates are located by the Jetspeed Template (and Decorator) Locator Component. These components
+locates templates using a normalized name/value pair URL scheme.
+using this scheme in what is called a 'normalized' URL to either a decorator or layout.
+However, templating engines such as Velocity need to work with templates using paths to templates that are
+relative of a document root. The <a href='guide-jpt.html'>Jetspeed Power Tool</a> facilitates conversion between normalized
+and relative paths. Typically in the Spring configuration, the template root of all decorators is defined as:
+<source test=""><![CDATA[
+${applicationRoot}/WEB-INF/decorations
+]]></source>
+and the root of all layouts (per portlet application) is defined as:
+<source test=""><![CDATA[
+${applicationRoot}/WEB-INF/templates
+]]></source>
+The Normalized Path is defined with named pair values. Examples:
+<source test=""><![CDATA[
+type/layout/media-type/html/name/tigris/decorator.vm
+type/decorator/media-type/html/language/en/country/US/name/metal/decorator.vm
+]]></source>
+<table>
+ <tr>
+ <th>Name</th>
+ <th>Value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>layout | portlet | generic</td>
+ <td>The type of template locator. Expected to be either one of the following values
+ <b>layout</b>, <b>portlet</b> (decorator) or <b>generic</b> (decorator). Layouts can be for either page layouts
+ or decorators. Generic type decorators can be used
+ for either portlets or page decorations.</td>
+ </tr>
+ <tr>
+ <td>media-type</td>
+ <td>html | wml | dhtml | ...</td>
+ <td>The markup media type to be located. Should be a valid media type (html, dhtml, wml...)</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>A valid decorator or layout name</td>
+ <td>The name of the decorator or layout. Usually corresponds to a
+ sub-directory holding the decorator or layout templates, images and stylesheets.</td>
+ </tr>
+ <tr>
+ <td>language</td>
+ <td>A valid ISO-639 standard two-character language abbreviation</td>
+ <td>ISO-639 (http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt) defines a standard for language abbreviations.
+ Typical abbreviations are en for english, fr for french, de for German, ...</td>
+ </tr>
+ <tr>
+ <td>country</td>
+ <td>A valid ISO-3166 standard two-character country code abbreviation</td>
+ <td>ISO-3166 (http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) defines a standard for country code abbreviations.
+ Typical abbreviations are US for United States, FR for France, ...</td>
+ </tr>
+
+</table>
+
+</p>
+</section>
+
+<section name='Terminology'>
+<table>
+ <tr>
+ <th>
+ Term
+ </th>
+ <th>
+ Definition
+ </th>
+ </tr>
+ <tr>
+ <td>
+ Layout
+ </td>
+ <td>
+Defines the fashion in which grouping of Fragments
+will organized relative to the final, aggregated
+content of a request to the portal. Layouts are defined by
+a portlet which applies an algorithm to a template to
+generate the aggregated content of a page. Typical
+algorithms are two column, three column, nested.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ TODO: left off here:
+ </td>
+ <td>
+ fragment, decoration, page, page decorator, portlet decorator,
+ application relative, normalized template path, absolute URL
+ </td>
+ </tr>
+</table>
+</section>
+</body>
+</document>
+
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org