Table of Contents |
---|
Downloading Wookie
You will need to download and install Apache Ant in order to build from source. See http://ant.apache.org
Wookie is designed to be downloaded using subversion; to checkout the latest code:
svn co
http://svn.apache.org/repos/asf/incubator/wookie/trunk
If you are a committer you should use https:// rather than http://
...
You can run Wookie in a number of different configurations, as described in the following sections.
Panel |
---|
NOTE: There is a known issue when using Ant version 1.8.x to build and run Wookie; you should instead use version 1.7.1. To check which version of ant you are using, type ant -version. See the FAQ for more information. |
Configuring your IDE
Wookie use uses Apache Ivy to resolve dependencies, you will therefore need the IvyDE plugin available at http://ant.apache.org/ivy/ivyde/index.html.
...
To run Wookie in standalone mode:
ant clean-db cd PROJECT_HOME_DIRECTORY
ant run
The first time you run wookie (or compile it) any required libraries will be downloaded, this can take some time and requires a network connection.
The "clean-db" target Note that by default, wookie will clean the database each time it is run, this ensures that your development environment starts in a consistent state. However, any modifications you have made to the database during previous runs will be lost.
...
Once the server is running go to http://localhost:8080/wookie
To access the administration menu (http://localhost:8080/wookie/admin) use the username 'java' and password 'java'.
If you want to start with a completely clean build then use:
cd PROJECT_HOME_DIRECTORY
ant clean-build clean-db run
Running options
To set run mode options you can either add properties to the local.build.properties
file or you can pass properties in via the command line using -Drun.args="<property_name>=<property_value> <property_name>=<property_value>"
. For example:
...
For more on remote debugging with Eclipse see http://www.eclipsezone.com/eclipse/forums/t53459.html
Note, you can set up a run configuration to be able to run Wookie from the UI of Eclipse, but I'll leave that for you to work out as I use the command line.
...
The following will compile and run the server in Tomcat with a MySQL databasespecified RDBMS using JPA persistence. The database tables will be set up automaticallyschema can be defined and populated on launch, however you must have previously created a database called "widgetdb" with username "java" and password "java". (If you want to change the database connection settings, then you need to alter the scripts/mysql/hibernate.cfg.xml.)
Edit the "build.properties" file as follows:
- uncomment "project.using.mysql=true" and comment out "project.using.derby=true"
- set "servletEngine.webapp.dir=" to the location of your tomcat webapps directory.
done the following:
1. Obtained a JDBC driver jar file for the database,
2. created an empty database for Wookie's persistent storage, and
3. have valid database credentials to access it.
Make the following changes to configure build.properties, (substituting CATALINA_HOME with the absolute or relative path to Tomcat's installation directory and specifying the database driver, url, type and credentials connection information):
widget.deploy.dir=CATALINA_HOME/webapps/wookie/deploy
servletEngine.webapp.dir=CATALINA_HOME/webapps
servletEngine.container.lib.dir=CATALINA_HOME/lib
servletEngine.context.conf.dir=CATALINA_HOME/conf/Catalina/localhost
wookie.persistence.manager.type=jpa
wookie.db.user=java
wookie.db.password=java
wookie.db.driver=com.mysql.jdbc.Driver
wookie.db.uri=jdbc:mysql://localhost:3306/widgetdb
wookie.db.type=mysql
jdbc.driver.path=../mysql-connector-java-5.1.7.jar
The wookie.db.type setting can accept the following values: db2, derby, hsqldb, mssql, mysql, mysql5, oracle, oracle9, oracle10, postgresql, and sybase. The jdbc.driver.path setting can be absolute or relative file path to the driver jar archive.
To ensure the configuration changes are propagated into the Wookie build artifacts, perform a full clean build after changing build.properties:
cd PROJECT_HOME_DIRECTORY
ant clean-build deploy-webapp
To force Wookie to define or reset the database schema on the first start, use the following commands to start the Tomcat server:
cd PROJECT_HOME_DIRECTORY
export CATALINA_OPTS="-Dwidget.persistence.manager.initstore=true"
CATALINA_HOME/bin/startup.sh
To shutdown the Wookie Tomcat server and clear the initialization flag:
cd PROJECT_HOME_DIRECTORY
CATALINA_HOME/bin/shutdown.sh
export CATALINA_OPTS=
There are also SQL scripts for all of the valid database configurations built as part of Wookie that can be used to initialize the database schema manually if desired. These are located here:
build/classes/org/apache/wookie/beans/jpa/db2-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/derby-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/hsqldb-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/mssql-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/mysql5-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/mysql-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/oracle10-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/oracle9-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/oracle-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/postgresql-wookie-schema.sql
build/classes/org/apache/wookie/beans/jpa/sybase-wookie-schema.sql
The Wookie server will populate the newly initialized database with seed data to complete the process when started.
You will need to create Create a user with the role "widgetadmin" in your tomcat installation. For example, add the following to tomcat-users.xml:
<role rolename="widgetadmin"/>
<user username="java" password="java" roles="widgetadmin"/>
...
Then to build and deploy the webapp, run:
ant deploy-webapp
Once Wookie is deployed, you can setup the MySQL tables by running:
ant clean-db
You can then start Tomcat as usual.
To access the administration menu (http://localhost:8080/wookie/admin) use the username 'java' and password 'java'.
...
ant clean-build deploy-webapp
If you want to clean the database use:
ant clean-db
By default Wookie connects to MySQL using Hibernate and the C3P0 connection pooler.
Once the server is running connect your debugger to port 8000. If "suspend=y" is used, it will will block, waiting for a debug connection before starting the server.
Running Wookie with a security manager
NOTE: This section was written before moving from Hibernate to OpenJPA/JCR and so some of these instructions may no longer be correct.
If you are running Wookie with a security manager you will have to grant some permissions to get Wookie running properly. Otherwise you are likely to run into this of a similar error:
No Format |
---|
SEVERE: Exception sending context initialized event to listener instance of class org.apache.wookie.server.ContextListener java.security.AccessControlException: access denied (java.util.PropertyPermission user.dir read) at ... |
If you can't turn off the security manager but don't really care about it, you can consider to replace to contents of the policy file (in Tomcat this is typically $TOMCAT_HOME/conf/catalina.policy
, Ubuntu users will find the policy files in /etc/tomcat6/policy.d/
) with the grant all statement:
No Format |
---|
grant {
permission java.security.AllPermission;
};
|
...
Code Block |
---|
// fixes access denied (java.util.PropertyPermission user.dir read) grant { permission java.util.PropertyPermission "*", "read,write"; }; // fixes access denied (java.io.FilePermission TOMCAT_HOME\bin\local.widgetserver.properties read) grant { permission java.io.FilePermission "<<ALL FILES>>", "read, write"; }; // fixes access denied (java.net.SocketPermission localhost resolve) grant { permission java.net.SocketPermission "*", "resolve,connect"; }; // fixes access denied (java.lang.RuntimePermission accessClassInPackage.org.apache.catalina) // fixes access denied (java.lang.RuntimePermission accessDeclaredMembers) // fixes access denied (java.lang.RuntimePermission getProtectionDomain) grant { permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina"; permission java.lang.RuntimePermission "accessDeclaredMembers"; permission java.lang.RuntimePermission "getProtectionDomain"; }; // fixes access denied (java.lang.reflect.ReflectPermission suppressAccessChecks) grant { permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; }; |
...
For more information how to do this in Tomcat, see the Security Manager HOW-TO
Running Wookie using embedded Jackrabbit JCR
The folloing property is used to switch the standalone or Tomcat deployed servers to utilize JCR for persistence via an embedded JCR instance:
wookie.persistence.manager.type=jcr
Additional properties must be configured to specify the desired JCR root node path and credentials for tomcat deployments:
wookie.repository.user=java
wookie.repository.password=java
wookie.repository.rootpath=/wookie
wookie.repository.workspace=default
These replace the wookie.db.* and jdbc.drive.path settings above, but otherwise the instructions apply for the JCR configuration.
Running Wookie with other configurations
Other configurations of Wookie can also be run; the main requirements are a servlet container and a database. The setup information for databases can be found in the /scripts directory. How these are loaded into configurations is defined in build.xml; the main requirement is to define connection details in scripts/database/hibernate.cfg.xml and to define the database setup script in scripts/database/widgetdb.sql
Database connections can be set up using either JPA (Java Persistence API) or JCR; the configuration details are set in build.properties. Additional configuration for advanced use can be found in org.apache.wookie.beans.jpa/peristence.properties. The database schema and mappings is located in etc/ddl-schema.
The deploy-webapp task can be used to deploy Wookie to any servlet container application.
Running Wookie in a virtual host configuration
This has been noted as an issue with the current release (see WOOKIE-111).
If anyone has any advice on resolving this issue, then please do comment on the issue using the link above.