In this chapter, we will cover:
Creating the installer from the source code
Installing ADempiere
Debugging the ADempiere client application (Desktop version)
Debugging the ADempiere server application (Web version)
Running multiple instances on a single machine
Giving ADempiere your identity
Before we get started with the real customization work in ADempiere, it is very important that we set up the right environment for the development and equip ourselves with the tools required for the customization. Most important among them is the ability to debug the existing code, so that when we make changes to the existing code or add a new functionality, we would have a way to find out the source of the problem, identify the cause, and make the necessary change to resolve it.
With this goal in perspective, in this chapter, we will understand how to setup ADempiere development environment and the different deployment mechanism which can be applied to the operational aspect of ADempiere. The chapter starts with the focus on the development environment where we will see how to check out the code from the ADempiere SVN repository, build it, create an installer from it, use the installer to install ADempiere on your system, debug the client version of ADempiere, and debug the server version. Subsequently, we will move on to the operational aspect where we will understand what it takes to run multiple instances of the ADempiere server on a single machine. As part of this, we will cover different deployment topologies, keeping the database and the application server in perspective and understand the topology-wise differences.
With most of the Open Source applications, it is more likely that you will customize or enhance ADempiere to suit yours or your customers' needs and you would like to give it your identity. You may want to give it a different name, use a different logo, or a different look-and-feel. We will cover this aspect in the last recipe of this chapter.
Like any other software application, ADempiere also requires certain software to be installed and configured on your system. In order to be able to customize or enhance ADempiere, you need a few more tools/applications and we have to have them properly configured before we start on our goal. Though not mandated by ADempiere, throughout this book, we will use the following list of software on the MS Windows platform:
Note
Though ADempiere supports Oracle and Oracle XE databases, for this book, we will use PostgreSQL database to keep these things simple and light.
The steps to install and configure the previously listed software are out of this book's scope. You may refer to http://wiki.postgresql.org/wiki/Detailed_installation_guides for the installation steps. Each one of these software come along with their own installation and setup manual. Kindly refer to them for installation and configuration. There is no specific configuration requirement for using this software with ADempiere. So, if you follow the respective installation manuals, you will be fine. However, at the end of the installation of all the software, ensure that the following environment variables are set and they are valid:
JAVA_HOME
For ease of reference, let us assume that the following is the installation path for the previously listed software on your system and the corresponding name that we will use to refer to those paths:
Eclipse Galileo —
C:\EclipseGalileo – ECLIPSE_HOMEJBoss 4.2.3 GA —
C:\JBoss_423_GA – JBOSS_HOMEJDK 1.6 or above —
C:\Java\jdk1.6_X JAVA_HOMEPostgreSQL Database 8.x —
C:\postgresql8.x – POSTGRES_HOME
At this point, we are all set to get started on our tour of ADempiere customization and enhancement.
The recipe describes the steps involved in building the ADempiere source code and creating an installer out of it, which is ready for you to install on your own system or any other system. These installer images are installable on MS Windows as well as Linux systems.
This is the basic recipe and a pre-requisite for any other recipe mentioned in this book.
1. Check out the ADempiere code from the following SVN URL:
https://adempiere.svn.sourceforge.net/svnroot/adempiere/tags/adempiere360lts.
Say, we have checked out the ADempiere code in the C:\adempiere_svn\ tags\adempiere360lts folder. We'll refer to the C:\adempiere_svn folder by name, say, ADEMPIERE_SVN
2. Start Eclipse.
3. Click on File menu and select Import...
4. Select the Existing Projects into Workspace option under the General category and click on the Next button. Dialog with the title Import Projects appears with the Select root directory radio button.
 |
 |
 |
7. Expand the
adempiere_360project in Eclipse. You will see the utils_dev folder.8. Expand the utils_dev folder and you will find build.xml. This is the Ant build script to compile the ADempiere source code and create the installable binaries.
9. Right click on build.xml and select Run As | Ant Build. This will start the build process.
 |
The following message appears in the console at the end of the build:
 |
A successful build will create the adempiere folder under the project folder and the following binary installers are created, which can be used to install ADempiere on MS Windows or Linux:
Adempiere_360LTS.zipAdempiere_360LTS.tar.gz
 |
In step 1, we first get the ADempiere code from its SVN repository. In steps 2 through to 6, we compile the code. In steps 7 through to 9, we create the distributions (Linux as well as MS Windows) by running the default Ant target inside the build.xml file, present under the utils_dev folder
In this recipe, we saw how we can use the Ant build file build.xml to compile the code and create the installation packages (.zip and .tar.gz files). The same can be achieved by running a batch file.
Now that we have created the installers in the previous recipe, here we will make use of it to install an instance of ADempiere for our use. This recipe describes the steps involved in installing and setting up the ADempiere instance to make it usable.
1. Create a new database in PostgreSQL by name, say, adempiere360.
2. Add the adempiere user in the PostgreSQL database with adempiere as the password.
3. Stop and restart PostgreSQL.
4. Copy the
<ADEMPIERE_SVN>\ tags\adempiere360lts \adempiere\Adempierefolder and its content toC:\. Now, you will have theC:\Adempierefolder.5. Set the environment variable
ADEMPIERE_HOMEtoC:\Adempiere.
1. Open a command prompt by selecting
Start Button|Run|Openand entercmd.2. Change the directory to
<ADEMPIERE_HOME>\data.3. Run the following commands to set up the ADempiere schema:
psql -U adempiere -d adempiere360 -c "drop schema sqlj cascade" psql -U adempiere -d adempiere360 -f Adempiere_pg.dmp >> dump_errors.log.
When prompted, enter adempiere as the password.
4. Change the directory to
<ADEMPIERE_HOME>.5. Run
RUN_setup.bat. This will bring up a window to enter various details.6. Enter the valid values.
|
Database Server |
|
|
Database Type |
|
|
Database Name |
|
|
Database User |
|
|
Database Password |
|
|
System Password |
<your PostgreSQL database admin user password> |
7. Click on the Test button. First time setup will pop up the Key Store Dialog. Enter the relevant details, as shown in the following screenshot, and click on the tick button:
 |
8. Click on the Test button and verify that all the tests have been passed (a tick mark appear next to the fields, as shown in the following screen shot):
 |
10. Accept the license term, when prompted. This will create an
Adempiere.propertiesfile in the <ADEMPIERE_HOME> folder.11. When setup is complete, change directory to <ADEMPIERE_HOME>.
12. Run
RUN_Adempiere.bat. This will start the client version of ADempiere and will show you the following login screen.
 |
13. Click on the 
button, which is on the right-hand side of the Server field, and verify that the database connection details is correct. Change the settings, if needed, and click on the Test Database button to make sure that the cross icon changes to a tick icon, as shown in the following screen shot:
 |
14. If you want to run the server version of ADempiere, then change the directory to <ADEMPIERE_HOME>\utils and run
RUN_Server2.bat. This will deploy ADempiere in JBoss, which is distributed along with it, and start the JBoss server. After the server has been started, you may verify your ADempiere installation by accessing the following URL from the browser of your choice —http://localhost:8080/webui—8080 is the default JBoss port. If it is different in your case, replace8080with your JBoss' port number. This needs to be done to ensure that the port that you are using for your JBoss server instance is free; otherwise the server will not run.To stop the server, you shall run RUN_Server2Stop.bat.
First, we create the database and import the ADempiere data dump using steps 1 through to 3. In steps 4 through to 10, we complete the initial setup of our ADempiere instance with details such as database detail, mail server detail, and so on, so that it is ready to run. Steps 11 through to 13 helps us to run the desktop as the well as web version of ADempiere.
Alternatively, to import ADempiere schema and the initial (GardenWorld) data, you may go to the<ADEMPIERE_HOME>\utils folder and run the RUN_ImportAdempiere.bat file.
Debugging the client version is pretty straightforward and quick. In this recipe, we will see how to configure the project in Eclipse so that we can debug ADempiere when we run it as a client application (the Swing version).
Before we can run ADempiere, there are properties, specific to ADempiere, which need to be configured properly for example, JDK location detail, application server detail, database detail, SMTP detail (for e-mails), and so on. The following steps must be completed to ensure that these properties are set up correctly:
1. In Eclipse, open the Open Resource window and select the
Setup.javafile. It is available under theinstall\src\org\compiere\installpackage of youradempiere360ltsproject.2. Right-click on the
Setup.javafile in the Project Explorer and select the optionRun As|Java Application. This will launch an ADempiere setup screen.
 |
For the client version, we need to set the fields in the following sections of the screen:
Java
Adempiere
Database Server
Mail Server (Optional)
Click on the Test button and if everything was set correctly, you will see the Ok message at the bottom of the setup screen. In case you get errors, verify the values you have entered. Correct them and Test until you get the Ok message. Any errors during the testing are also shown on this window.
Note
In case any errors occur during your practice and it is not described in the book, you may refer to the ADempiere Wiki and forums for more information.
3. Click on the Save button. This will create the
Adempiere.propertiesfile in the Adempiere Home directory. After creating the property file, the program tries to build the code base but fails with a build error. Do not worry! Our intention was to only get theAdempiere.propertiesfile created, which we will use in our subsequent setups.
Now that we have got the Adempiere.properties file out, it is a trivial task to be able to debug the application. Here are the steps:
1. In Eclipse, open the Open Resource window and select the
Adempiere.javafile. It is available under thebase\src\org\compierefolder of youradempiere_360project. This class is the entry point class for the client version.
 |
2. Add a break-point at Line 594 inside the main method.
3. Right-click on the
Adempiere.javafile and select Debug As|Debug Configuration. This will bring up the Debug Configurations window.
 |
4. Click on the Arguments tab and specify the following VM arguments:
DPropertyFile="C:\adempiere_svn\tags\adempiere360lts\ADempiere.properties" DADEMPIERE_HOME="C:\ tags\adempiere360lts"
PropertyFile:Points to theAdempiere.propertiesfile, which we had created earlierADEMPIERE_HOME:Points to the Adempiere folder
 |
Adempiere.java is the main class file which provides the entry point for the desktop version of ADempiere. This is the class where you will find the main method. To this class, the two important properties—PropertyFile and ADEMPIERE_HOME must be passed so that it can read the setup information (database, mail server, JRE path, and so on) and run the application.
Working with the web/server version of ADempiere is equally practical and required as compared to the client/desktop version. The server version runs inside a J2EE container, like JBoss. In this recipe, we will see how to configure ADempiere and JBoss to be able to debug the code when it is deployed as a server. Though ADempiere comes along with a JBoss distribution, to have a better understanding of the subject matter, we will use the external JBoss installation.
1. In Eclipse, go to the Servers view.
2. Right-click and select New | Server. You will see the New Server window.
 |
3. On the New Server window, select the JBoss V4.2 and click the Next button. This will take you to the New JBoss V4.2 Runtime window.
 |
 |
5. On the New JBoss v4.2 Server window, enter the following and click the Next button:
Address:
127.0.0.1Port:
9080(make sure that this port is not being used by any other application on your system)JNDI Port:
1099(make sure that this port is not being used by any other application on your system)Server Configuration:
defaultClicking on the Next button will take you to the Add and Remove window:
 |
 |
|
8. Open
org.adempiere.webui.AdempiereWebUI.javaand add a break-point inside the constructor.9. Right-click on the server entry, which we just created, and select the Open menu option.
 |
10. On the Overview screen, change the Start value under the Timeouts category to 500.
 |
Note
For the default
Server Configuration, the port number is defaulted to 8080 unless you go and change the config files of JBoss, which we'll see in the subsequent recipe. For now, note that even though you enter 9080 as the port, the JBoss server will run on port 8080. So, make sure that port 8080 is free on your system.
11. Click on the Open launch configuration. This will bring up the Edit configuration window to edit the JBoss configuration.
 |
12. On the Arguments tab, add the following to the VM arguments:
-DPropertyFile="C:\adempiere_svn\tags\adempiere360lts\ADempiere.properties" DADEMPIERE_HOME="C:\adempiere_svn\tags\adempiere360lts"
13. On the Classpath tab, click on the Add External JARs button to add the JARs from the following folders:
<ADEMPIERE_SVN>\tags\adempiere360lts\tools\lib
Note
Exclude the following JARs:
ant.jar, ant-commons-net.jar, ant-contrib-1.0b1.jar, ant-launcher.jar, j2ee.jar, jnlp.jar, log4j.jar, commons-logging.jar, servlet-api.jarNote
Exclude the following JARs:
jfreechart-1.0.13.jarAdd <JAVA_HOME>\jre\lib\javaws.jar
15. Refresh the project
adempiere_360.16. Right-click on the JBoss server entry on the Servers view and select the Publish menu option. This will start the process of build and deployment. The application is deployed with the context name
Adempiere_trunk.
 |
 |
This will start the JBoss server in the debug mode and the debugger will stop at your break-point. Using the Debug toolbar, you will be able to debug ADempiere as a server application. If you resume the application, the server will run and you will see the following screen when you access the URL
http://localhost:8080/Adempiere_trunk/in your browser.
 |
Steps 1 through 7 take care of creating a JBoss server entry in Eclipse and adding the ADempiere project deployment resource to the JBoss server runtime. It is important to verify that the JBoss and JNDI port numbers (9080 and 1099) are free. Steps 9 through 14 are where the project related detail (for example, classpath) is configured in the JBoss server runtime. This is important for the deployment of the ADempiere server version in JBoss and running the same. The configuration adds the required JAR files and ADempiere classes to the JBoss configuration so that they are available to the runtime when we run the server.
In this recipe, the focus is on running multiple instances of ADempiere on a single server. This is a very practical requirement when you want to host ADempiere for multiple clients on a single server. Even though each instance of ADempiere is meant to handle multiple clients and organizations, there may be a scenario where you may have to put up multiple instances of ADempiere not only from the technical perspective, but also from an operational perspective. For example, one instance is to be run on PostgreSQL whereas the other instance is to be run on Oracle. And, if you have that scenario, this recipe will try to address it.
Here, we are going to cover two deployment topologies. In one, we will have 1-1-1 mapping between JBoss, ADempiere, and Database, that is, one instance of JBoss server hosting one instance of ADempiere, which is connecting to one database. The following image depicts the 1-1-1 setup.
 |
In the second instance, we will have 1-N-1 mapping where one instance of the JBoss server will host multiple instances of ADempiere instances and each one of them will connect to a single database. The following image depicts the 1-N-1 setup:
 |
These steps are common to 1-1-1 as well as 1-N-1 setup.
Copy the
<ADEMPIERE_SVN>\tags\adempiere360ltsto<ADEMPIERE_SVN>\tags\adempiere360lts_2.Change the project name to
adempiere_360_2in the<ADEMPIERE_SVN>\tags\adempiere360lts_2\.projectfile.Import the
<ADEMPIERE_SVN>\tags\adempiere360lts_2project into Eclipse.Create the
adempiere360_2database in PostgreSQL and set up the schema and the initial data by following the steps mentioned in the Installing ADempiere recipe. Remember to use the already created useradempiere.
1. Running instance with 1-1-1 Setup.
Here we will set up one more JBoss and ADempiere instance.
Go to the
<JBOSS_HOME>\serverfolderCopy the default folder to
adempiere360lts_2. You may have any name for your serverModify the port numbers in the following files so that they are not shared with the default server ports and they are available on your system:
< JBOSS_HOME>\server\ adempiere360lts_2\conf\jboss-service.xml:Modify the following ports—8083, 1099, 1098, 4444, 4445< JBOSS_HOME>\server\ adempiere360lts_2\deploy\ejb3.deployer\META-INF\jboss-service.xml:Modify the following port—3873< JBOSS_HOME>\server\ adempiere360lts_2\deploy\jms\uil2-service.xml:Modify the following port—8093< JBOSS_HOME>\server\ adempiere360lts_2\deploy\jboss-web.deployer\server.xml:Modify the following ports—8080, 8443, 8009Open the
<ADEMPIERE_SVN>\tags\adempiere360lts_2\.settings\org.eclipse.wst.common.componentfile and change thedeploy-namefromAdempiere_trunktoAdempiere_360_2(you may have any name or your choice)Go to Eclipse and refresh the
adempiere_360_2projectFollow the steps mentioned in Debugging ADempiere server application recipe to add a new JBoss server pointing to
<JBOSS_HOME>\server\adempiere360lts_2and deployAdempiere_360_2to it. Make sure, yourPropertyFileVM argument points to theAdempiere.propertiescreated in<ADEMPIERE_SVN>\tags\adempiere360lts_2folder andADEMPIERE_HOME VMargument points to<ADEMPIERE_SVN>\tags\adempiere360lts_2Now, run the JBoss default server, where you had
Adempiere_trunkdeployed, and also run the second JBoss server where you haveAdempiere_360_2deployed
2. Running an instance with 1-N-1 Setup.
Go to Eclipse
Right-click on the JBoss server entry in the Servers view, which we had created with the default configuration and to which
Adempiere_trunkwas deployed, and click Add and Remove. You will seeAdempiere_trunklisted under the Configured items andAdempiere_360_2listed under the Available itemsAdd
Adempiere_360_2to the Configured list and click on the Finish buttonRight-click on the JBoss server entry and click Publish to deploy
Adempiere_360_2. Adempiere_360_2will be the context for this ADempiere instanceRight-click on the JBoss server entry and click on Start the server with two instances of ADempiere deployed. You can now access the two instances by accessing the following URLs:
Both ADempiere instances will be pointing to the same database as the database connection detail is mentioned in the Adempiere.properties file and a common property file is used in the VM arguments of the JBoss server.
In order to have an instance with 1-1-1 setup, important point to make is making sure that we are able to run multiple instances of the JBoss server on a single machine. This requires us to make changes to the different port numbers, which one or another service in JBoss uses. If this is not done, some or some other service would not run and that would lead to an error while we try to deploy and run the application.
In the 1-N-1 setup, JBoss ports are not of concern as we will be running a single instance of it. However, the important point here is the deployment name for the multiple instances of the ADempiere application. Uniqueness must be maintained across ADempiere instances in terms of deploy-name, otherwise the deployment of one instance will overwrite the deployment of a second instance, as it uses the deploy-name as the WAR filename.
If you are reading this book, you have, or may have, some customization or enhancement needs in your mind. Be it look and feel (UI color, CSS, icons and so on), name, or logo. Effectively, we would have a practical need to give ADempiere our own identity. Here we will discuss the various points where you may make the changes to have your own identity of the application.
Verify that you have completed the following recipes:
1. Creating the Installer from the source code.
2. Installing ADempiere.
3. Debugging the ADempiere server application.
Change, say,
NAMEto your application name inbase/src/org/compiere/ADempiere.java. Additionally, you may also change thesplash images, product images, product sub-title, and so onChange, say,
APP_NAMEto your application name inzkwebui/WEB-INF/src/org/adempiere/webui/ADempiereWebUI.javaCSS—For the web application, which is based on the ZK UI framework, you can modify the
<ADEMPIERE_SVN>\tags\adempiere360lts\zkwebui\css\ default.css.dspfile to modify the stylesImages—There are lots of images. They include images used as ADempiere logos/icons of various kinds, button icons, toolbar icons, and other UI-related images. The simplest way to replace an existing image with yours is to:
Search for the files with
.ico,.png,.jpg,.jpeg, and.gif extensions in the<ADEMPIERE_SVN>\tags\adempiere360ltsfolder
Find the image of your interest and note down that image dimension and type (jpg/png/gif/ico/and so on)
Create your image of the same dimension and type
Replace the existing image with your image
Launch the ADempiere application and notice the difference
Here is a custom identity that I have given by changing the application name and the logo:
 |
In the preceding diagram, we have changed the application name to Eagle and the logo with my EagleRP product logo. Similarly, you shall be able to make other changes you may need to give ADempiere your identity.
After you have done this, you may also want to commit the same in your project repository so that for all the subsequent builds and deployments, you will use this repository where all the CSS and new images will be part of the installer.
