In this blog I describe how to setup Ace Operator as an Eclipse project for development. This blog is only useful for developers who want to browse the code and makes changes to the code. This blog is also useful for software contributors and more technically-minded language translators.
I have previously described how to build and install Ace Operator from the sources in my blog about Installation. The blog provided some insight into how to checkout the source code from the SourceForge Subversion repository and build using Maven. Those steps were sufficient for someone trying to build Ace Operator from the sources but if you are a software contributor or want to make some changes to the software, you need to have tools to browse through the code, use a good language-sensitive editor, debug, etc. We use the Eclipse IDE for all our development. I will provide you some information on how to setup the Eclipse to work with Ace Operator although Ace Operator is not IDE-centric and you can use any other IDE for developing Ace Operator.
Eclipse Download and Installation
First, you need to install Oracle Java Development Kit (JDK) 1.6. Next, you need to download Eclipse from the Eclipse Web Site. I use the Eclipse Helios Release but you should download the latest stable release. There are various Eclipse bundles and I suggest using the Eclipse IDE for Java EE Developers as it comes with various tools that you will need. Next, you will need a set of plugins. I have installed the following plugins:
- M2Eclipse – http://m2eclipse.sonatype.org/sites/m2e
- GWT Designer – http://dl.google.com/eclipse/inst/d2gwt/latest/3.6
- Subclipse – http://subclipse.tigris.org/update_1.6.x
- Eclipse Resource Bundle Editor: https://sourceforge.net/projects/eclipse-rbe/. This plugin is optional and is only needed if you are going to be doing language translations extensively.
Checking out Ace Operator and Building
Once you are done setting up Eclipse, the next step is to checkout the Ace Operator from the Subversion repository. You can find information on the repository from the SourceForge Project Site. You can use the Subclipse plugin you installed (see above) to browse the repository and checkout. Bring up the SVN Repositories view from the Window->Show View menu. You have a few choices:
- If your goal is to browse the code, I suggest checking out from one of the labels (tags). For instance, you could checkout labels/2.0.0.
- If your goal is to apply a fix to the code, I suggest checking out from one of the branches. For instance, you could checkout branches/2.0.
- If you are contributing/planning to contribute to Ace Operator source code, please contact the administrators of the Ace Operator project. If we like what you want to contribute, we will assign you a specific branch to work from.
The repository already contains the Eclipse project files and when you checkout the project, it will automatically setup the project on your workspace.
To build the project, select the project from the Project/Package Explorer, right click to get the popup menu, select Run As->Maven Install. The build process will download all the dependent artifacts from the Internet and perform a full build which will take a few minutes depending on your Internet connection speed and CPU and RAM on your computer. At the end of the process, you will have the binary packages under the target folder.
Creating Child Projects
Although you can now build the entire project from the sources, you still need to create Java projects for you to browse through the code more easily, make changes and refactor. For that, you have to create child Maven projects. Unfortunately, there is no concept of hierarchical project structure in Eclipse so far but you can still use it quite effectively using the procedure I describe below.
You will notice that under the root ace project, there are several directories. For example, the ace-web directory holds the Java project for the chat client and the Java Servlets for the chat application. If you want to make changes, you will have to create the ace-web as a project in Eclipse. To create the project, right click on the Project/Package Explorer, and select New->Project... Select Project as the type of project, not Java Project or any other types of project. Click on the Next button to bring up the project name and location dialog box. From this dialog box, select the project name as ace-web and uncheck the Use Default Location check box. Then, using the Browse button, select the location of the ace-web project (it is under the ace/ace-web directory under your Eclipse workspace directory). Click the Finish button to complete the process. You will see the ace-web project on the Project/Package Explorer with the project source displayed using the Java project look that you may already be familiar with.
Create the other child projects in a similar manner. Once completed, you are now ready to make changes to the code. You can build individual projects if you want using the Run As->Maven install from the project menu to save time but in some cases, you need to do the full build. For example, if you made changes to the ace-framework project, you may need to build ace-app project because there are dependencies between the two.
Running, Testing and Debugging
Now that we know how to build the code, lets figure out how to run the code and test. To test the software, install the prerequisite software (Tomcat, MySQL). Please refer to my blog on Installation for details.
Once all the prerequisite software has been installed, we need to initialize the database and the configuration files. To do this, follow the steps below:
- Copy the ace-installation/src/main/assembly/.ace directory to your home directory. In Linux, your home directory is typically /home/username and on Windows 7, it is C:\Users\username.
- Make sure that MySQL is running and you have the root password handy. If you just installed MySQL, make sure you have secured the root access with the mysqladmin tool that comes with MySQL.
- Make sure that you created the ace-installation child project as explained in the above section.
- Run the post-installer to initialize the configuration file and the database. From the ace-installation child project, navigate to the package src/main/java -> com.quikj.ace.installer. To launch the Installer, right click on the Install.java file and from the popup menu, select Run As->Java Application. This will bring up the Installer application user interface. Follow the steps and complete the setup. If you are unsure about the answers you need to provide, read my blog on Installation.
- Configure the SSL certificate as explained in my blog on Installation.
Setting up Tomcat
Eclipse comes with a Server tool (part of WTP) that is quite handy for developing and debugging. It allows you to start and stop various supported servers from within Eclipse, view the logs in the console, start in debug mode, etc. You can use this tool to manage the Tomcat server during development.
To add the Tomcat Server, navigate to Window->Preferences->Server->Runtime Environments and click on the Add button. Select the Tomcat version you downloaded from the list and provide the name of the directory where Tomcat has been installed. To manage the server, open the view Servers by navigating to Window->Show View->Server->Servers. From the Server view, you can start and stop the server among other things.
You may need to enable SSL on the server as Ace Operator requires this setting. To configure SSL, open the server.xml file from the the Package/Project Explorer and navigate to Servers->Tomcat->server.xml. Uncomment the SSL connector configuration and save the changes.
You may also need to set some properties to Tomcat launcher for it to work correctly. They are:
-Dcom.quikj.server.web.trace=true -Dcom.quikj.server.web.trace.message=true -Dfile.encoding=UTF8
To set the properties, double-click on the Tomcat server you created from the Servers view to open the server configuration. Click on the Launch Configuration link and add the above properties to the VM Arguments section. Note that you will need to use quote (“) characters around the properties in case a property value contains blank spaces.
The next task is to add the Ace Operator web applications to the Tomcat so that when the Tomcat server starts up, Ace Operator applications also start up. To add the Ace Operator applications, double-click on the Tomcat server from the Server view to open the server configuration window. Click on the Modules tab at the bottom of the editor and add the following web applications clicking on the External Web Module button:
- Path: /ace-communicator, Document Base: your-eclipse-workspace\ace\ace-communicator\target\ace-communicator-2.0.0
- Path: /ace-contactcenter, Document Base: your-eclipse-workspace\ace\ace-web\target\ace-web-2.0.0
- Path: /ace-custom, Document Base: your-eclipse-workspace\ace\ace-custom\target\ace-custom.
Start the Tomcat and make sure you see the logs pertaining to the Ace Operator application startup. Bring up a browser and test that all the applications you added above works. Now you are all set to manage Tomcat from Eclipse.
Using the GWT Shell
This completes my blog on how to setup and use Ace Operator with the Eclipse IDE. I have left out some of the details for you to figure out but if you have any questions or think that parts of the blog need further elaboration, please contact me.