Customizing ART

manual (35)
Timothy Anyona Timothy Anyona

Customizing ART

You can customize ART to fit your needs.

Using live files

You can customize or update ART files directly on the application server where ART is deployed. This may be especially useful for minor changes.

Setting up Apache Ant

If you are going to customize the application source code, you may want to setup Apache Ant to make compiling your changes easier. To do this, take the following steps

  • Download the Apache Ant zip package from http://ant.apache.org/
  • Extract the zip file to C:\, or other directory of your choice. A new directory will be created e.g. C:\apache-ant-1.8.1
  • Add the Ant bin directory to the PATH environment variable e.g. C:\apache-ant-1.8.1\bin

Customizing java files

Java source files are contained in sub directories under the ART_HOME\WEB-INF\classes\art directory. To make customizations to these files, take the following steps.

  • Configure Apache Ant as described above
  • Make changes to the desired .java files
  • Open a command prompt window and navigate to the TOMCAT_HOME\webapps\art directory
  • Type the command ant compile
  • The modified .java files will be recompiled
  • Reload the ART application using the Tomcat Application Manager, or restart tomcat
  • The application will now use the modified source code

Customizing jsp files

JSP files can be modified and results immediately viewable when the relevant page is refreshed. If you don't see the expected changes when you refresh the page, the page displayed may be a cached copy. You may need to clear the application server cache and the browser cache to ensure the page is refreshed. If using Tomcat, you can clear the tomcat cache by deleting the TOMCAT_HOME\work\Catalina\localhost\art directory. If using Firefox, you can clear the browser cache from the History | Clear Recent History menu.

Customizing other files

Other files that affect how ART works can also be modified. Examples include

  • ART_HOME\WEB-INF\classes\quartz.properties - Change quartz configuration items e.g. number of threads
  • ART_HOME\WEB-INF\classes\logback.xml - Change logging level for quartz or ART classes

Updating jasperreports

If you are using a version of iReport that is different from the jasperreports version contained in ART, you may want to update the jasperreports version contained in ART to match your iReport version. This may not be necessary, but would be useful if you encounter problems while running reports. Take the following steps to update the jasperreports library and template files.

  • Download the required jasperreports .jar from the jasperreports sourceforge page, http://sourceforge.net/projects/jasperreports/files/jasperreports/ e.g download the file jasperreports-5.0.1.jar from the JasperReports 5.0.1 folder.
  • Ensure Apache Ant is set up as described above
  • Stop Tomcat
  • Backup the contents of the ART_HOME\WEB-INF\work\templates directory, where the jasperreport template files reside
  • Delete the jasperreports .jar file contained in the ART_HOME\WEB-INF\lib directory
  • Copy the just downloaded jasperreports .jar file to the ART_HOME\WEB-INF\lib directory
  • Open a command prompt window and navigate to the ART_HOME directory
  • Type the command ant clean-jasperreports
  • Type the command ant compile-jasperreports
  • Restart Tomcat

Your reports should now work properly.

Using Ant

If you don't wish to modify the live files, e.g. you want to test the changes on a test server first, you can modify the files in another location and create an application .war file to deploy on your test environment.

Using Ant without an IDE

  • Ensure Apache Ant is set up as described above
  • Unzip the PACKAGE_PATH\art.war e.g. unzip to a new directory PACKAGE_PATH\art
  • Using a text editor, make modifications to the required files
  • Open a command prompt window and navigate to the PACKAGE_PATH\art directory
  • Type the command ant war
  • A new file named art.war will be created in the PACKAGE_PATH\art directory. Deploy this file to your desired application server.

Using Ant with NetBeans

Instead of using a text editor to make changes and Ant to compile and package the changes, you can use an IDE to do this. The following are sample steps using NetBeans 7.2.1.

  • Unzip the PACKAGE_PATH\art.war file e.g. unzip to a new directory PACKAGE_PATH\art. You can unzip the war file the same way as any zip file e.g. using 7zip.
  • Create a directory to hold NetBeans project files e.g. C:\MyNetBeansProjects\art
  • Open NetBeans
  • Select the File | New Project menu
  • Select the Java Web category and Web Application with Existing Sources project and click on the Next button
  • For the Location field, select the PACKAGE_PATH\art directory. For the Project Folder field, select the directory you created for this e.g. C:\MyNetBeansProjects\art. Click on the Next button.
  • Select the Server to use e.g. Apache Tomcat and Java EE version e.g. Java EE 7 Web. Click on the Next button.
  • The Existing Sources and Libaries dialog should be pre-populated correctly with the appropriate paths. Click on the Finish button. If prompted, choose to delete existing .class files.
  • Make changes to the files as appropriate
  • To test the changes, use the Run Project icon on the menu bar, or right click on the project in the Projects explorer and select Run.
  • To debug the code, set breakpoints as appropriate by clicking on the edge of the editor at the desired line of code and use the Debug Project icon on the menu bar or right click on the project and select Debug. If the debug process doesn't start with NetBeans indicating that it is waiting for tomcat to stop, open Task Manager and kill the java.exe process.
  • To generate a war file to deploy, right click on the project and select Clean and Build. The generated art.war file will be located in the C:\MyNetBeansProjects\art\dist directory. Deploy this file to your desired application server

Using Maven

You can take the following steps to modify ART source code, using Apache Maven as the build tool. ART source files with a maven structure will be found in the PACKAGE_PATH\src directory.

  • Install Maven
  • (Optional) Install a maven repository manager e.g. Sonatype Nexus. A repository manager is optional but greatly increases productivity.

Using Maven without an IDE

  • Using a text editor, make modifications to the required files
  • Open a command prompt window and navigate to the PACKAGE_PATH\src\art-parent directory
  • Type the command mvn clean package
  • A new file named art.war will be created in the PACKAGE_PATH\src\art-parent\art\target directory. Deploy this file to your desired application server.

Using Maven with NetBeans

The following are sample steps using NetBeans 7.2.1.

  • Open NetBeans
  • Select the File | Open Project menu
  • Select the PACKAGE_PATH\src\art-parent directory in the left hand panel, and click on the Open Required Projects box on the right hand panel. Click on the Open Project button.
  • Make changes to the files as appropriate
  • To test the changes, right click on the art project in the Projects explorer and select Run. Select the server on which to deploy the application and click on OK.
  • To generate a war file to deploy, right click on the Parent project and select Clean and Build. The generated art.war file will be located in the PACKAGE_PATH\src\art-parent\art\target directory. Deploy this file to your desired application server

Using Maven with Eclipse

The following are sample steps using Eclipse Juno (4.2) SR2.

  • Download the Eclipse IDE for Java EE developers package
  • Unzip the package to your desired location e.g. C:\, to generate a C:\eclipse directory. Run the C:\eclipse\eclipse.exe file.
  • Ensure you have an internet connection
  • Select the Help | Eclipse Marketplace menu
  • On the Search tab, in the Find field, type maven and hit enter
  • Find the "Maven Integration for Eclipse" plugin (m2e by eclipse.org) and click on the Install button
  • Once the plugin installs, go back to the Eclipse Marketplace and again type maven in the Find field and hit enter
  • Find the "Maven Integration for Eclipse WTP" plugin (m2e-wtp by eclipse.org) and click on the Install button.
  • Create a directory to hold eclipse workspace files e.g. C:\MyEclipseWorkspaces\art
  • In Eclipse, select the File | Switch Workspace | Other menu
  • Select the workspace folder you created e.g. C:\MyEclipseWorkspaces\art and click on OK. Wait for Eclipse to restart
  • Select the File | Import menu
  • Open the Maven group, select the Existing Maven Projects option and click on Next.
  • Set the Root Directory field to the PACKAGE_PATH\src\art-parent directory. This should list the art-parent project, with the artdbcp, artmail and art projects beneath it. If the projects aren't retrieved, try to hit the enter key after typing the path in the root directory field. Ensure all the projects are selected and click on Next.
  • Click on Finish in the final screen.
  • Click on the Restore icon in the left most panel to have the project windows displayed on the screen and close the welcome page.
  • Make changes to the files as appropriate
  • Ensure you have a JDK installed
  • Select the Window | Preferences menu. Expand the Java group and select the Installed JREs option. In the right hand panel, select the default JRE and click on the Edit button. Set the JRE home field to a JDK folder e.g. C:\Program Files\Java\jdk1.8.0_20. Instead of editing the default JRE you can also use the Add button to add a new one and then check it as the default workspace JRE.
  • Right click on the art-parent project and select the Run As | Run Configurations menu. Select the Maven Build option, and then click on the New launch configuration icon at the top of the list. Give a Name to the configuration e.g. package and set the Base directory to the PACKAGE_PATH\src\art-parent directory. In the Goals field, type clean package. In the JRE tab, ensure the JRE selected is the one defined earlier. Click on the Apply button. To generate a war file immediately, click on the Run button.
  • To test changes, set up a server. See https://github.com/OneBusAway/onebusaway/wiki/Setting-Up-a-Tomcat-Server-in-Eclipse . Convert the art webapp project to a Dymanic Web Module and run the application. See https://wiki.base22.com/display/btg/How+to+create+a+Maven+web+app+and+deploy+to+Tomcat+-+fast
  • To generate a war file to deploy, click on the drop down on the Run As icon in the menu bar, and select the configuration you created e.g. package. The generated art.war file will be located in the PACKAGE_PATH\src\art-parent\art\target directory. Deploy this file to your desired application server

Custom Export Path

By default, if the output for a report creates a file e.g. pdf, this file is stored in the ART_HOME\WEB-INF\work\export directory. You can designate a different directory to be used as the export path e.g. to a location on the application server that contains more disk space. To do this, modify the ART_HOME\WEB-INF\art-custom-settings.json file and set the path in the exportDirectory field.

Translating ART

You can translate ART so that the user interface is displayed in your own language. Follow the following steps to translate ART.

  • Download the latest ART package, unzip it and unzip the art.war file using any zip/unzip software. Get the ArtMessages.properties file from the WEB-INF\i18n directory and and make a copy of it, naming your new file in the format ArtMessages_xx.properties, where xx is the ISO 639-1 language code for your language. A List of these language codes can be found here - http://www.mathguide.de/info/tools/languagecode.html. An example would be ArtMessages_pt.properties for Portuguese. If your language is written differently in different countries you can add the 2 letter country specifier to the file name so that your have a file name like ArtMessages_pt_BR.properties for Brazilian Portuguese. You can find a list of country codes here - http://www.immigration-usa.com/country_digraphs.html.
  • Change all the text in your new properties file after the = signs to your language
  • If your language uses a non ISO-8859 character set (e.g. chinese, arabic, russian etc) name the file ArtMessages_xx-UTF8.properties and then decode it to an ISO-8859 character set with UTF-8 escapes using the native2ascii tool that is available with your Java installation. An example command is as below.

    native2ascii ArtMessages_xx-UTF8.properties ArtMessages_xx.properties
    
  • Once you have your translated properties file in the i18n folder, you can restart the application server to make the new translation available to the application, or wait for 1 hour after which the messages are refreshed.

  • Now you can log in to the application and include the lang=xx parameter in browser url to activate the new language e.g. http://localhost:8080/art/reports?lang=xx
  • If you would like the new language to be listed for selection within the application e.g. on the login page, add the language code and the language name to the ART_HOME\WEB-INF\languages.properties file, save the file and restart the application server.
  • If in addition you would like this new translation to be included in future ART versions, email the properties file to tanyona (at) users.sf.net or create a new post on the Discussion forum and attach the file there.

Related

Discussion: JasperReports with sub reports problem
Discussion: Maven build
Discussion: Support for clustered app server environment

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks