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 ta...@apache.org on 2005/04/27 21:46:45 UTC
cvs commit: jakarta-jetspeed/xdocs fusion-db.xml database.xml fusion.xml
taylor 2005/04/27 12:46:44
Modified: xdocs database.xml fusion.xml
Added: xdocs fusion-db.xml
Log:
- Fusion documentation continued
- improved Database docs included torque-om docs
Revision Changes Path
1.2 +48 -14 jakarta-jetspeed/xdocs/database.xml
Index: database.xml
===================================================================
RCS file: /home/cvs/jakarta-jetspeed/xdocs/database.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- database.xml 3 May 2004 17:31:35 -0000 1.1
+++ database.xml 27 Apr 2005 19:46:44 -0000 1.2
@@ -34,20 +34,30 @@
<li>Oracle</li>
<li>Postgres</li>
<li>Sybase</li>
+ <li>(MS) SQL Server</li>
+ <li>Axion</li>
+ <li>Cloudscape</li>
+ <li>db2400</li>
+ <li>Interbase</li>
+ <li>SAP DB</li>
</ul>
<p>
Scripts for setting up the database are included with the source code distribution, under the src/sql/external folder.
-To change the database connection, you will also need to have the source code since Jetspeed uses Torque.
+To change the database connection, you may will also need to have the source code since Jetspeed uses Torque.
Torque generates Java bindings specific to the backend database, requiring that the source be rebuilt.
The war file installation automatically configures Hypersonic SQL as the default database.
</p>
-<p>
-Steps to configure Jetspeed with another database:
-<ul>
-<li>1. Edit project.properties (or your $HOME/build.properties), and set the 'database' property to one
- of these values [db2,hypersonic,mysql,oracle,postgresql,mssql,sybase]
-</li>
-<li>2. Edit webapp/WEB-INF/conf/Torque.properties. Uncomment and change the following properties for your database:
+<subsection name='1. Torque Database Connection Properties'>
+<p>Edit <b>project.properties</b> (or your $HOME/build.properties), and set the <b>database</b> property to one
+ of these values [db2,hypersonic,mysql,oracle,postgresql,mssql,sybase,axion,cloudscape,db2400,interbase,sapdb]
+</p>
+<source><![CDATA[
+# Example:
+database = mysql
+]]></source>
+<p>Edit <b>webapp/WEB-INF/conf/Torque.properties.</b>
+ Uncomment and change the following properties for your database:
+</p>
<source><![CDATA[
### MySQL
### torque.dsfactory.default.connection.driver = org.gjt.mm.mysql.Driver
@@ -65,13 +75,37 @@
### torque.dsfactory.default.connection.user = jetspeed
### torque.dsfactory.default.connection.password = jetspeed
]]></source>
-</li>
-<li>3. Rebuild the source: <b>maven dist</b>
-</li>
-<li>4. Run the database 2 turbine- and populate- scripts for your particular database found in src/sql/external
-</li>
-</ul>
+</subsection>
+<subsection name='2. Download or Build Torque OM Bindings JAR'>
+<p> Torque, unfortunately, requires that you recompile some of your source, or bindings file, to run with a particular database.
+ For example, Oracle uses sequences, and other databases do not. Thus you have to place in specific bindings jars for each database.
+ You can download the prebuilt driversfrom here: <a href='http://www.bluesunrise.com/maven/jetspeed/distributions/torque-om/'>Torque Bindings Download</a>
+ and go to the directory for your particular database. Place the downloaded <b>jetspeed-torque-om-1.6.jar</b> for your database and in your
+ jetspeed WEB-INF/lib directory in your deployment or WAR distribution.
+</p>
+</subsection>
+<subsection name='2a. Build Torque OM Bindings JAR'>
+<p> Optionally, you want to build the Torque OM binding jar from source:
</p>
+<source><![CDATA[
+cd torque-om
+vi project.properties
+# EDIT property: torque.database
+# SAVE
+maven
+# this creates the jetspeed-torque-om-1.6.jar in the target directory.
+]]></source>
+</subsection>
+<subsection name='3. Run Database Scripts'>
+<p>
+Run the database 2 turbine- and populate- scripts for your particular database found in src/sql/external
+</p>
+</subsection>
+<subsection name='4. Fusion Database Setup'>
+<p>
+ If using Fusion, <a href='fusion-db.html'>follow the Fusion Database</a> instructions.
+</p>
+</subsection>
</section>
</body>
</document>
1.2 +141 -19 jakarta-jetspeed/xdocs/fusion.xml
Index: fusion.xml
===================================================================
RCS file: /home/cvs/jakarta-jetspeed/xdocs/fusion.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- fusion.xml 20 Apr 2005 04:35:58 -0000 1.1
+++ fusion.xml 27 Apr 2005 19:46:44 -0000 1.2
@@ -34,20 +34,20 @@
in the default build.
</p>
<p>
- In the summer of 2004, the Jetspeed Fusion project was developed.
Fusion enables Jetspeed-1 to run standard Java Portlet applications in Jetspeed-1.
This was made possible by leveraging the component architecture in Jetspeed-2.
The Jetspeed-2 portal engine is compliant with the Java Portlet Standard.
Fusion embeds the Jetspeed-2 portal engine inside of the Jetspeed-1 portal.
</p>
</subsection>
- <subsection name="Running Jetspeed Fusion">
- <p>Jetspeed Fusion does require more configuration than a plain old Jetspeed 1.6 installation.
+</section>
+<section name="Running Jetspeed Fusion">
+ <p>Jetspeed Fusion does require more configuration than a standard Jetspeed 1.6 installation.
This is because of the nature of the Portlet API: portlet applications are deployed as WAR files
and run in their web application, separate from the portal. With Fusion, we need to install several
support jars into the common or shared class path area of your particular application server. The 1.6
release comes with a packaged Fusion and Tomcat 5 combination, ready to run. If you are installing to your
- own application server, you will need some extra setup for Fusion to run. In this example, we are use Tomcat 5.
+ own application server, you will need some extra setup for Fusion to run. In this example, we are using Tomcat 5.
The following jars need to be placed into Tomcat's shared/lib directory:
</p>
<table>
@@ -81,11 +81,11 @@
</tr>
</table>
- <i>The <b>*</b> denotes a particular version, such as 2.0-M2 for example.</i>
- <p>See the section on building from source below for details on how to automate the process.</p>
-
- </subsection>
- <subsection name="Deploying Portlet Applications">
+ <i>The <b>*</b> denotes a particular version, such as 2.0-M3 with Jetspeed 1.6.</i>
+ <p>See the section on building from <a href="#Building Fusion">source</a> below for details on how to automate the process.</p>
+ <p>If you are using Hypersonic, Fusion requires a second database instance to be running.</p>
+</section>
+<section name="Deploying Portlet Applications">
<p>
Deploying a portlet application to Jetspeed is very easy. Make sure that Jetspeed is running in an application server.
In this example, we will assume its Tomcat.
@@ -106,25 +106,147 @@
find JSR-168 standard portlets: <b>JSR-168</b> and <b>Portlet API</b>. Once you've selected the portlets
in the customizer, you can then start using the portlets immediately.
</p>
- </subsection>
- <subsection name="Running Fusion on App Servers">
+ </section>
+ <section name="Running Fusion on App Servers">
<p>
Fusion should run on any application server. We have a Wiki page with the status of successfully installed
application servers and the instructions on how to do so here: <a href="http://wiki.apache.org/portals/Jetspeed2/Fusion">Fusion Wiki</a>
</p>
- </subsection>
- <subsection name="Building Fusion">
+</section>
+<section name="Building Fusion">
<p>
The instructions here are for those who would like to build Fusion from source.
By default, Jetspeed 1.6 builds without Fusion. To build Fusion, enable the build by
- setting this property in your $HOME/build.properties:
+ setting this property in your $HOME/build.properties and then follow the instructions in this section:
</p>
<source test=""><![CDATA[
org.apache.jetspeed.fusion = true
- ]]></source>
-
- </subsection>
-
-</section>
+
+ # this property is required for the Jetspeed-1 Plugin
+ # its usually set to your Tomcat home, for example:
+ maven.war.appserver.home = /home/jetspeed/jakarta-tomcat-5.0.30
+
+ ]]></source>
+<subsection name="Build 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</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>
+</subsection>
+<subsection name='1. Get Maven Ready'>
+<p>If you have not already done so, download and install Maven.</p>
+</subsection>
+<subsection name='2. Build Properties'>
+<p>Please set these values in your ${USER_HOME}/<code>build.properties</code> file:</p>
+<table>
+ <tr>
+ <th>property</th>
+ <th>example</th>
+ <th>what is it?</th>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.project.home</td>
+ <td>/home/apache/jakarta-jetspeed-2/</td>
+ <td>The root of your Jetspeed-2 source installation (see example on left).</td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.server.home</td>
+ <td>${CATALINA_HOME}/</td>
+ <td>The root of your Tomcat server installation.</td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.catalina.version.major</td>
+ <td>5</td>
+ <td>Are you using Tomcat 5.0.x (use: 5) or 5.5.x? (use: 5.5)</td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.server.shared</td>
+ <td>${org.apache.jetspeed.server.home}/shared/lib/</td>
+ <td>The location of the shared jars in your Tomcat installation.</td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.deploy.war.dir</td>
+ <td>${org.apache.jetspeed.server.home}/webapps/</td>
+ <td>The location to deploy web application in Tomcat.</td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.services.autodeployment.user</td>
+ <td>your-tomcat-manager-user</td>
+ <td>a Tomcat user with the manager role.
+ See the Tomcat Configuration section below.
+ </td>
+ </tr>
+ <tr>
+ <td>org.apache.jetspeed.services.autodeployment.password</td>
+ <td>your-tomcat-manager-user-password</td>
+ <td>The password of the Tomcat manager user.</td>
+ </tr>
+</table>
+<p>
+To develop or deploy Jetspeed with another database (not the default HSQL), see the property configuration in the
+<a href='database.html'>Database Configuration documentation</a>.
+</p>
+</subsection>
+<subsection name="3. Tomcat Configuration">
+<p>
+Fusion now can use the Tomcat manager application for managing portlet applications through
+its new Portlet Application Lifecycle Manager Portlet.
+To be able to do so it needs a configured Tomcat user with the predefined 'manager' role in
+the ${CATALINA_HOME}/conf/tomcat-users.xml.
+</p>
+<p>
+A minimal example tomcat-users.xml could look like:
+ <source><![CDATA[
+ <?xml version='1.0' encoding='utf-8'?>
+ <tomcat-users>
+ <role rolename="manager"/>
+ <user username="j2deployer" password="j2deployer" roles="manager"/>
+ </tomcat-users>]]>
+ </source>
+Make sure to use a more appropriate username and password. <br/>
+With the above example the required autodeployment properties should be set as:
+ <pre>
+ org.apache.jetspeed.services.autodeployment.user=j2deployer
+ org.apache.jetspeed.services.autodeployment.password=j2deployer
+ </pre>
+</p>
+</subsection>
+<subsection name="4. Database Configuration">
+<p>
+ See the Fusion <a href='fusion-db.html'>Database Configuration page</a>.
+</p>
+</subsection>
+<subsection name='5. Building with Maven'>
+ <p>
+ Now that you have all the requirements and properties configured, you are ready to go.
+ Change directory to the jetspeed-1 source home, and run the following commands:
+ </p>
+ <source><![CDATA[
+ maven clean war
+ ###############################################
+ # optional, only required if using Hypersonic
+ cd fusion
+ maven db.fusion.start
+ # (new shell required here unless you run the previous command in another shell)
+ cd ..
+ ###############################################
+ ## if you are using another database, make sure to copy the JDBC driver into the
+ ## app server's classpath. With Tomcat5, JDBC drivers co into common/endorsed
+ maven deploy
+ cd ${TOMCAT_HOME}/bin
+ startup(.sh|.bat)
+ ]]>
+ </source>
+</subsection>
+</section>
</body>
</document>
1.1 jakarta-jetspeed/xdocs/fusion-db.xml
Index: fusion-db.xml
===================================================================
<?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 Fusion Database</title>
<subtitle>Configuring Fusion for Databases</subtitle>
<authors>
<person name="David Sean Taylor" email="taylor@apache.org"/>
</authors>
</properties>
<body>
<section name="Default Database">
<p>
The default database distributed with Fusion 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.fusion.test.database.default.name=mysql
org.apache.jetspeed.fusion.test.database.url = jdbc:mysql://j2-server/j2test
org.apache.jetspeed.fusion.test.database.driver = com.mysql.jdbc.Driver
org.apache.jetspeed.fusion.test.database.user = jetspeed2
org.apache.jetspeed.fusion.test.database.password = whatever
# -------------------------------------------------------------------------
# configure MySQL Production DB
# -------------------------------------------------------------------------
org.apache.jetspeed.fusion.production.database.default.name=mysql
org.apache.jetspeed.fusion.production.database.url = jdbc:mysql://j2-server/j2
org.apache.jetspeed.fusion.production.database.driver = com.mysql.jdbc.Driver
org.apache.jetspeed.fusion.production.database.user = jetspeed2
org.apache.jetspeed.fusion.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 ='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.fusion.test.database.default.name=oracle
# org.apache.jetspeed.fusion.test.database.ojb.platform=oracle9i
# org.apache.jetspeed.fusion.test.database.url = jdbc:oracle:thin:@j2-sever:1521:j2db
# org.apache.jetspeed.fusion.test.database.driver = oracle.jdbc.driver.OracleDriver
# org.apache.jetspeed.fusion.test.database.user = j2test
# org.apache.jetspeed.fusion.test.database.password = whatever
# -------------------------------------------------------------------------
# configure Oracle Production DB
# -------------------------------------------------------------------------
# org.apache.jetspeed.fusion.production.database.default.name=oracle
# org.apache.jetspeed.fusion.production.database.ojb.platform=oracle9i
# org.apache.jetspeed.fusion.production.database.url = jdbc:oracle:thin:@j2-server:1521:j2db
# org.apache.jetspeed.fusion.production.database.driver = oracle.jdbc.driver.OracleDriver
# org.apache.jetspeed.fusion.production.database.user = j2
# org.apache.jetspeed.fusion.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 ='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:
</p>
<source test=""><![CDATA[
maven db.scripts.gen
maven dropdrops
maven db.create.test (only when running unit tests)
maven 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.fusion.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.fusion.test.jdbc.drivers.path=/Portal/lib/MySQL/mysql-connector-java-3.0.8-stable-bin.jar
org.apache.jetspeed.fusion.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.fusion.test.jdbc.drivers.path=/Portal/lib/oracle/ojdbc14.jar;/Portal/lib/oracle/nls_charset12.jar
org.apache.jetspeed.fusion.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.fusion.test.jdbc.drivers.path=/Portal/lib/oracle/classes12.jar;
org.apache.jetspeed.fusion.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}/common/endorsed/
</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org