Orca
Documentation
Download
Portals
Orca actors are components that are written in Java using the Shirako toolkit. They run within JVM containers. Actors may run within JVM containers launched from the command line, or within a Web application server such as Tomcat, or within a development environment such as Eclipse. Install/configure is slightly different in each case.
To create and install Orca actors, you must build the sources from the Orca repository, as described here. At present we do not support binary installation. The sources are self-contained and the build process will retrieve any necessary dependencies from the Orca Maven repository.
Note: This guide presumes that you have a full-featured Java development environment set up. If not, you might want to start with the developer notes .
Our current implementation and the build process require that the build be performed on a Linux/Unix machine. Future releases will strive to eliminate any platform dependencies. Before you can obtain Orca's sources and build the project you will need to have the following software installed on the build machine:
Orca does not compile under Java 1.6 due to a dependency on a third-party library that causes problems with JDK 1.6. We are working on addressing this issue and apologize for any inconvenience.
For details about the installation of any of the above systems please refer to their respective web sites.
The top of the Orca repository can be found at:
https://svn.nicl.cs.duke.edu/svn/cereus/orca
The repository is organized as follows:
The release portion of the repository can be accessed anonymously. Accessing any other part of the repository requires a developer account. If you wish to be granted a developer account, please contact a member of the project.
To describe the process of checking out the code from the Orca repository we will assume that you want to access the official release with version X.X.X. To check out the code navigate to the directory where you wish the source code to be checked out and type the following in your terminal:
svn co https://svn.nicl.cs.duke.edu/svn/cereus/orca/release/X.X.X orca
The above command will result in the source code being download to your machine and stored in a folder named orca. In the rest of this guilde we will refer to the location of the folder orca as ORCA_HOME.
Now that you have installed all prerequisite software and have downloaded the project sources, you are ready to build the project.\
Important : the first time you build the project you must be connected to the Internet. The build process will attempt to download any necessary dependencies during the first invocation. Failure to obtain a dependency will prevent the build from completing.
To build the project issue the following commands:
cd $ORCA_HOME mvn install
The above command will build the whole project, downloading any necessary dependencies, and will install the resulting files in your local Maven repository (Usually located under $HOME /.m2/). If any errors occur during the build, please retry the above commands. Intermittent network connectivity can cause the build process to fail. If the problem persists, please record the output and contact a project member.
You now have the Orca project compiled and installed in your local Maven repository.
If you plan to launch your own container, you need to decide where you will run it. The container is a server: in general, the container will persist and receive invocations on a public IP address, and it will store state in a local database. You can launch a container directly within your $ORCA_HOME using command-line scripts. Or you can run it on a remote machine, e.g., under a Web application server. Wherever you run the container it will need the right tools installed.
Each Orca container requires access to a database server. At present Orca supports only MySQL version 5.0 or above.
Before you proceed further, you must ensure that you have access to a database server. If you do not have access to a database server you must install one and be empowered to administer it. Please consult the MySQL web site for details about installation.
Note: On a Debian/Ubuntu machine MySQL can be installed by typing the following:
sudo apt-get install mysql-server
If you want to run the database server on a separate machine from the container that uses it, make sure that the server is configured to accept incoming network connections. By default MySQL is installed with network access disabled. To enable network access edit /etc/mysql/my.cnf on the machine where the server is installed. Search the file for 'bind-address'. If your machine has a fixed ip address, set bind-address to it, otherwise comment bind-address and MySQL will accept connections from all network interfaces connected to your machine. You will need to restart the server after changing the configuration file:
/etc/init.d/mysql stop /etc/init.d/mysql start
To enable Orca to access the database server, you need to create a database user identity and a database. We will use the following notation:
Assuming that you have root access to the database server, you can create the Orca user using the following commands. For the standard null DB_USER_PASSWORD, put nothing between the single quotes ('').
mysql -u root -p
[enter your admin password]
grant all privileges on ${ORCA_DB_NAME}.* to '${ORCA_DB_USER}'@'$HOST' identified by '${ORCA_DB_USER_PASSWORD}';
Now that you have configured the database access, you need to create the database schema and load some data into it. Orca consists of multiple components and each of them may need to extend the underlying database with additional tables. At present, we do not have the support for dynamically changing the database as components are enabled/disabled. Therefore, in addition to the individual component schema files, we also provide a master schema file that combines all individual schema files. The master schema file is located in $ORCA_HOME/schema/mysql/full.schema.sql.
If $ORCA_DB_NAME is not the default (orca), you will have to edit the master schema file. At the top of the file you will find the following lines:
drop database if exists orca; create database orca; USE `orca`;
Replace the first three occurrences of orca with $ORCA_DB_NAME.
Note
: If you are working on a development branch, please do not edit the master file. Make a copy of the master file and edit the copy, not the original. This will prevent accidentally checking in your changes.
With the schema file updated, we are now ready to create the database schema. Type the following in your terminal:
mysql -u $ORCA_DB_USER -p -h $ORCA_DB_SERVER < $ORCA_HOME/schema/mysql/full.schema.sql [enter password]
If an error occurs when issuing the above command, make sure that you have followed all the above steps. If the error still persists, please contact a project member.
The next step in configuring the database is to populate the tables with some data. The master data file is located in $ORCA_HOME/schemas/mysql/full.data.sql. Similarly to the master schema file, if you changed the default database name you will need to edit this file. Please consult the instructions above (Note: you only need to edit the first line from the data file).
To load some basic initial data (standard resource type descriptors, etc.) in the container database, type the following in your terminal:
mysql -u $ORCA_DB_USER -p -h $ORCA_DB_SERVER < $ORCA_HOME/schema/mysql/full.data.sql [enter password]
If you plan to run any of the unit tests, you will also need to create a separate database in your server to be used for unit testing. This database must be called test , it must be accessible by user test , and it must reside on a MySQL server on the same machine (localhost) where the tests will run. Please follow the instructions above to create the database. To load the database schema and the data use $ORCA_HOME/schema/mysql/test.schema.sql and $ORCA_HOME/schema/mysql/test.data.sql
Congratulations! You have successfully completed the database configuration.