jira rev002

Intro to JIRABY RICH HELTON

(SUN CERTIFIED (SC) JAVA PROGRAMMER, SC JAVA DEVELOPER, SC ENTERPRISE ARCHITECT)

Trouble Ticketing

There are also many trouble ticketing systems like Remedy, Trackit, and Jira that provide trouble ticketing support.

These slides will look at Jira because quoting Gartner:

“ A major part of its appeal is its high degree of configurability at an extremely low price point”.

I will add my quote “Its extremely easy to customize the code and to modify its internal workings to do specific tasks.”

Jira

Jira, referenced from http://en.wikipedia.org/wiki/JIRA_(software), is a bug tracking, project management, and issue tracking software.

This product is not open source, but the source code is available, and many plugins are open source.

The main engine uses Open Symphony and XML to develop the workflow.

The GUI uses Apache Velocity and JSPs that are highly customizable.

The Engine executes itself in a Apache Tomcat Web Start environment using scripting.

Jira

Jira provides an API to write directly into their product http://docs.atlassian.com/software/jira/docs/api/latest/.

They also maintain plugins to the latest Java IDE environments for development, including NetBeans IDE and Eclipse.

The database schema that JIRA uses is also documented http://confluence.atlassian.com/display/JIRA/Database+Schema .

Jira plugins can be found at https://plugins.atlassian.com/search/by/jira , and range from Active Directory, Crystal Reports, MS Project servers, to many customization tools. By using these plugins, users can create their own custom fields, screens and even charts.

The benefits of Jira are listed in their 2004 Software awards, http://www.consensus.com.au/SoftwareAwards/CSAarchive/CSA2004/JIRA.htm .

Jira

Jira

Jira is built using multiple Open Source Java frameworks. The most basic one to understand is its Web Container that starts Jira called Apache Tomcat.

Web Containers

Tomcat

Tomcat is a Servlet and Java Server Pages Container developed by Apache, reference http://en.wikipedia.org/wiki/Tomcat_(software) and http://tomcat.apache.org/ .

It provides a Java HTTP Server to run Java code. Catalina is Tomcat’s servlet container. A servlet container a Java class that responds to HTTP requests.

A HTTP request is an HTTP page that will call Java code and execute an action running on the Tomcat Server.

The Tomcat server may be started with a startup script and use different ports so that many servers may be provide different services.

Benefits of Tomcat/Catalina

Tomcat can run a web server by just starting the startup.bat or startup.sh.

It uses other scripts to setclasspath, start catalina shutdown.

A directory structure is used locally that can contain the classes, libraries, configurations, etc.

This way multiple tomcat server can be used in their own containment area, or directory, without affecting other instances of the Java Web Server.

The Tomcat Web Server is Operating System dependent, and does not require a formal installation or setup to be run. Only that the directory and its contents are copied over correctly.

Again, all of this is Open Source.

Tomcat Directory

Tomcat Directory

bin Directory containing the scripts and Tomcat JAR files.

conf The properties and XML files that configure the server, including ports, Admin ports, database connections, etc.

lib The supporting JAR files needed to run Tomcat.

logs log files that are written during runtime and startup.

webapps any WAR files that contain the web applications. WAR files are similar to JAR files except they also contain the Web pages, like JSPs and Servlets. This is where the Flex applications will be stored.

Reference http://tomcat.apache.org/tomcat-3.3-doc/tomcat-ug.html#directory_structure

Jira has many of the same directories

Jira’s use of Tomcat

Tomcat, and Catalina, will be the Web Server and Web Services that runs the Jira framework.

This means that application logging will be managed by the Server, JAR files, startup and shutdown scripts, class paths, and most of the directory structure will be managed and modeled after Apache Tomcat.

Jira is deployed with a version of Tomcat that it is tested against and is embedded in the Jira product.

Catalina

Tomcat is the web server that presents HTML and Java Server Pages (JSP’s).

Catalina is the servlet code that responds on the server to server requests and sends its response in HMTL, JSPs and even XML.

A Servlet will receive a request and issue a response after processing the request. It may do a database lookup, call other code or many other tasks.

Catalina is a container that will pool, secure, and oversee these servlets as they are configured. The servlets are the binary code to be executed.

There is a Java Servlet protocol to be explored further at http://en.wikipedia.org/wiki/Java_Servlet#Servlet_containers

JSP lifecycle

JIRA JSPs

Jira has default JSP that are out of the box and associated Java Servets that are loaded in Tomcat from the atlassian-jira directory:

JIRA JSPs

With some skill in JSPs, these pages can be re-written to be customized beyond out of the box Jira. Looking at the default.jsp, it basically redirects the page to the Dashboard, we could change the code to send it to home page first:

Startup

Tomcat

As mentioned earlier, Jira is a Web Service running in Tomcat.

To start Jira is to start Tomcat. The bin directory contains all the scripts for Tomcat/Jira.

Here’s a sample of some of the scripts:

Tomcat

To start Tomcat/Jira, Linux will use “./startup.sh” and Windows will use “startup.bat”.

To shutdown Tomcat/Jira, Linux will use “./shutdown.sh” and Windows will use “shutdown.bat”.

The “/bin” directory contains the Tomcat/Catalina JARs and executables to start Tomcat, Catalina, and Jira.

Installing the JDK and JRE

Tomcat, Catalina and Jira requires the Java Development Kit (JDK) and Java Runtime Environment (JRE) to run.

The JDK is used for development and has development libraries.

The JRE is simply for runtime. To find out the JAVA_HOME for the JDK is set in LINUX, run:

It is set in the /etc/profile in UBUNTU:

Installing the JDK and JRE

Test the Java and run “java –version”:

Java

If Java is installed and working correctly, a lot of the work is done.

The point of Web Containers is to contain as much as the work in the container as possible and not interfere with the rest of the Operating system.

The Jira base directory, where Jira starts, will contain all the other JARs, pages, setups, configs, scripts, etc. In this case :

Tomcat like….

Jira uses some Tomcat defaults, and uses Tomcat to add its own flavor.

For instance, Tomcat will use the “conf” directory to define its configuration and Jira likes it:

Tomcat like….

The “server.xml” is very important. It will define the startup ports, the keystore file, the database location and login, and much more.

Here will we see the port is “8443”:

Keystore file

The Java keystore file is a rudimentary file that contains code signing, encryption keys, certifications, and various other encryption pieces that Java uses in encrypted flat file format.

It can be managed with the Java “keytool.exe” and was developed well before protocols like LDAP were well established.

In Jira’s case, it is required to find it and possibly offload some code signing tasks.

Data Store

The server.xml will also contain the connection information to the Jira database, like MySQL here:

Tomcat Unlike….

Normally Tomcat will contain WAR, Web Archive, files in the “webapps/Root/WEB-INF” directory.

Jira uses the “atlassian-jira/WEB-INF” directory instead.

The atlassian-jira/WEB-INF/lib”directory will contains most of the common libraries, plugins, language files, workflow and most of Jira’s libraries. This is the Jira pieces:

Jira Classes

Besides the libraries (JARS) found in the previous slide, therse are many compiled classes, properties and xml files that will define how Jira works internally.

The non-library files will be in the “atlassian-jira/WEB-INF/classes”:

Jira Classes

To add plugins to Jira is usually just adding a new JAR file, like WorkflowReport-1.3.1.jar, to the “atlassian-jira/ WEB-INF/lib” directory. In this example, new graphics are automatically added to show Jira workflow and configuration in the Jira GUI to support it.

For advanced functionality, a class could be created to debug this plugin as it runs, and the “log4j.properties” (logging) file can be changed to log it running, in the “atlassian-jira/WEB-INF/classes” directory.

This means that normally a plugin is just adding a file, but level of configurability can be taken to extreme by manipulating some of the class files and properties files that run Jira.

Let’s take it to the extreme and look at Jira workflow.

Jira Workflow

Jira Workflow

Jira is made up of dozens of Open Source efforts, from the Web Server to logging, so why should its workflow not be open source.

Jira uses Open Symphony OSWorkfow for its workflow design. Found at http://www.opensymphony.com/ .

In essence, the Jira default workflow will walk through a jira-workflow.xml file, found at “atlassian-jira/WEB-INF/classes”:

Jira Workflow

The jira-workflow.xml will define the various workflows, what actions are allowed, and based on the actions, what Java classes will be called to perform those actions.

Many of the functions that can be done straight in code can also be done through the Jira GUI. For instance, the Administrator->Workflow Schemes will rewrite the jira-workflow.xml through its GUI.

Jira Workflow Scheme GUI

More Jira Workflow

The jira-workflow.xml is the default Jira workflow, more workflows are created with more projects being added to the Jira server.

These new workflows follow the same OSWorkflow format but are now stored in the Jira Database defined in the server.xml.

The database workflows can be handcrafted from http://confluence.atlassian.com/display/JIRACOM/Unordered+workflow+transitions+(eg.+issue+approval) and http://confluence.atlassian.com/display/JIRACOM/Editing+JIRA+workflow+XML+by+hand

Jira Database

Jira Database

Jira’s default database is the HSSQLDB (Hyper Structured Query Language Database) which is a relational database management system written in Java. See http://en.wikipedia.org/wiki/HSQLDB .

HSSQLDB is loaded at runtime of Jira through its JDBC Java Database Driver, so it does not persist information in a database that is already loaded into the Operating System like MySQL or SQL Server. Therefore, HSSQLDB is normally used in a development environment.

Where is the data saved?The configuration of the HSSQLDB is saved in the “database/jiradb.properties” file.

The data of the HSSQLDB is saved in the “database/jiradb.script” file.

HS SQL

The HS SQL Jar file is located in the “common/lib” directory and the physical database is in the “database” directory, the HS SQL DB Manager can be called using “java -cp common/lib/hsqldb-1.8.0.5.jar org.hsqldb.util.DatabaseManager -user sa -url jdbc:hsqldb:database/jiradb”:

Jira Database Backup

Jira’s database data can be backed up and restored using the Jira backup tool:

Jira Database Backup

Note to this tool, it will backup the standard data from the database, it will not backup any of the configurations from the files, any plugin information, any libraries, or anything else.

It will have the ticketing information, fields, screens, and workflows.

If changes are made to Jira after the backup, it may not match the database fields anymore, and those changes to Jira will have to be reversed to the last known good backup.

Jira MySQL Migration

The easist way to migrate the Jira database from HS SQL to MySQL is to backup the HSSQL jiradb and restore the data into the MySQL database.

First, backup the Jira data and shutdown Jira. Install MySQL from http://www.mysql.com/downloads/mysql/

Create the jiraddb:mysql> create database jiradb character set utf8;

Create user “jirauser” password “XXXXXXXX”mysql> CREATE USER ‘jirauser’@’localhost’ IDENTIFIED BY

‘XXXXXXXX’;mysql> GRANT ALL PRIVILEGES ON *.* TO ‘jirauser’@’localhost’

WITH GRANT OPTION;

Jira MySQL Migration

See http://confluence.atlassian.com/display/JIRA/Setting+up+JIRA+Standalone+and+MySQL+on+Linux and http://confluence.atlassian.com/display/DOC/Known+Issues+for+MySQL for help.

Ensure the Database was created:mysql> show databases;+--------------------+| Database |+--------------------+| information_schema || jiradb || mysql || test |+--------------------+4 rows in set (0.00 sec)

Jira MySQL Migration

Set the server.xml to point to the MySQL database:

Jira is now empty data

Jira no longer has its standard data and starts in a default mode. Even the access control is empty. Start Jira with a temporary administration:

Jira is now empty data

Jira is now empty data

Keep going until the setup is complete:

Jira is now empty data

Now restore the data and all the data should be restored including going back to the original access controls:

Jira is now empty data

You are now using MySQL:

Looking through the schema

Now that the database is MySQL, you can use the MySQL Workbench on the database, http://wb.mysql.com/:

Looking through the schema

The Jira Schema is defined at http://confluence.atlassian.com/display/JIRA/Database+Schema :

Jira Logging

Jira Logging

Jira uses Tomcat Logging and also Open Source freeware logging Apache library called log4j. http://en.wikipedia.org/wiki/Log4j and http://logging.apache.org/log4j/1.2/ .

Many of the log4j and Catalina logs will be in the “logs” subdirectory:

Jira Logging

The catalina.out will show many of the issues like environmental issues like Java path, plugins missing, etc, here is a normal startup:

Jira Logging

The bin directory also contains a “atlassian-jira.log” that will show many of the Jira enviromental settings and concerns:

Jira Logging

A normal “atlassian-jira.log”:

Jira SQL Logging

Jira doesn’t use straight SQL calls to talk to the database, it uses a Open Source framework called Hibernate. http://en.wikipedia.org/wiki/Hibernate_(Java)

Knowing this is very helpful, especially in logging. If the restore of data does not work due to a change in the database table structure, logging levels can be set in log4j to log the SQL queries from Hibernate. http://confluence.atlassian.com/display/CONF25/Enabling+detailed+Hibernate+logging

More Jira Frameworks

Jira Builds

Jira uses another Apache Open source framework called Maven to build its code base as well as the plugins. Many pluigns and even some Jira code is available and Open Source. A section on Apache Maven will be given later.

Jira Templates

Jira uses a lot of custom fields and custom screens defined in its database. It cannot use static JSPs because the code will have to change when dynamic fields are created.

Jira uses another Apache Open Source called Velocity for its Web templates, see http://en.wikipedia.org/wiki/Apache_Velocity and http://velocity.apache.org/ .

Velocity is the template engine that will read objects and create Web graphics dynamically based on the structure of the objects.

Most of the Velocity templates, defined as *.vm files can be founds in “atlassian-jira/template/standard” and atlassian-jira/WEB-INF/classes/templates”.

Jira IoC

Many modern Java Architectures use Inversion of Control (IoC) which provides a consistent means building and managing Business objects using callbacks.

The most common is the Spring Framework, http://en.wikipedia.org/wiki/Spring_Framework .

Jira 4.0 will support plugins using the Spring framework, but Jira is built with Pico Objects using the Open Source PicoContainer framework http://www.picocontainer.org/ .

Customizing Jira IoC

Yes, even the internal object factories inside Jira can be customized http://confluence.atlassian.com/display/JIRA/Customising+JIRA+code :

ApacheMaven

What is it?

Apache Maven 2 is a software tool for Java project management and build automation.

It uses a .pom file in XML form that will generate a configuration for pulling down libraries from Maven repositories, building the project and even testing the project with results.

See http://en.wikipedia.org/wiki/Apache_Maven, http://maven.apache.org/guides/getting-started/index.html, http://maven.apache.org/guides/getting-started/index.html and http://maven.apache.org/ as a reference.

POM

The Project Object Model (POM) is used in Apache Maven to describe the software project being built.

The POM can also be generated using IDE’s like NetBeans that will use a plugin to Maven to generate the files.

The POM files are in XML format.

POM Example

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.mycompany.app</groupId> <artifactId>parent</artifactId> <version>1.0</version> </parent><dependencies> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> </dependencies></project>

Maven Directory structure

Maven uses a predefined directory structure called a standard project structure.

The pom.xml will be stored in the project home directory which is the base directory for the file tree.

From this base directory, there will be a src and target directory:

Maven Directory structure

The src/main/java directory is where the Java source code is stored.

The src/main/resources are where the application resources are stored like GIF files.

The src/main/config are where the configuration files are stored.

The src/main/webapp are where the web application WAR files are stored.

The src/test/java are where the Unit test files are stored.

Running Maven

The “mvn” command is used to run maven. It must be executed in the project home directory. Here are some of the commands:

Conclusion

Jira, not Open Source

Even though Jira is not Open Source, it has many, many people that are part of the coding community who discuss its internal working and has documented it. It also appears the ability to modify the internal workings of Jira and all of its components because most portions of the source code appear to be available from vendors wiki pages. Many of the frameworks that Jira utilizes are Open Source.