This page provides a very high level overview of JIRA's dependencies and the role each one plays in JIRA. This page makes references to external resources (websites, books) where one can find more information.
Technical Introduction to JIRA
As JIRA is a web application, users interact with JIRA using a web browser. JIRA uses OpenSymphony's WebWork 1 to process web requests submitted by users. Please note that WebWork 1, not 2, is used. WebWork 1 is a MVC framework similar to Struts. Each request is handled by a WebWork action which usually uses other objects, such as utility and Manager classes to accomplish a task.
JIRA uses JSP for the View layer. So most of HTML that is served to the user as the response to their web request is generated by a JSP. Therefore, to generate a response the WebWork action uses a JSP.
Also see JIRA Webwork Actions.
For more information on WebWork 1 please see its online documentation.
Almost all authentication in JIRA is performed through Seraph, Atlasian's open source web authentication framework. The goal of seraph is to provide a simple, extensible authentication system that we can use on any application server.
Seraph is implemented as a servlet filter. Its sole job is, given a web request, to associate that request with a particular user. It supports several methods of authentication, including HTTP Basic Authentication, form-based authentication (ie. redirect to an internal or external login form), and looking up credentials already stored in the user's session (e.g. a cookie set by a SSO system).
Seraph performs no user management itself. It merely checks the credentials of the incoming request, and delegates any user-management functions (looking up a user, checking a user's password is correct) to JIRA's user-management - OSUser (discussed later in this document).
If you were looking to integrate JIRA with a Single Sign-On (SSO) solution, you would do so by writing a custom Seraph authenticator (and in fact, many customers have done so). Please note that by default JIRA is not shipped with any SSO integration, customers have to write a custom Authenticator themselves. You may also want to check out Crowd and integrating JIRA with Crowd.
Another very important function that Seraph performs in JIRA is to only allow users with Global Admin permission to access WebWork actions that allow the user to perform administration tasks. These WebWork actions are accessed by URLs starting with "/admin". For more information on JIRA's permission please see JIRA's documentation.
For more information on how seraph works internally please see this page.
OSUser is OpenSymphony's user and group management framework.
OSUser provides the following functionality:
- Stores users and groups in JIRA's database
- Stores group membership (which users are part of which groups) in JIRA's db
- Stores user preferences (e.g. whether a user would like to receive HTML or Text e-mails)
- Authenticates users (checks if the users password matches)
- Provides API that allows to manage (create, delete) users, manage group membership (add and remove users from groups), and manage users' preferences.
As mentioned previously, Seraph delegates to OSUser to authenticate the user (i.e. check whether the correct password has been entered when a user tries to login).
OSUser uses the following tables in the database:
userbase- stores one record for each JIRA user
groupbase- stores one record for each JIRA group
membershipbase- stores which users are members of which group
userbase table only stores the numeric (arbitrary) id of the user, username, and a hashed password.
OSUser uses PropertySet (covered in the next section) to store user's e-mail address, and full name. PropertySet is also used to store user preferences. In JIRA the preferences include things like:
- whether the user would like to receive HTML or Text e-mail
- number of issues to display in JIRA's Issue Navigator
- whether to receive notifications for user's own updates to issues
- Locale (Language) of the user
OSUser also provides simple authentication against LDAP, which JIRA can utilise. Note, that only LDAP authentication is supported; the user records must still exist in JIRA's database. For more information on JIRA's LDAP autentication please see this document.
For more information on OSUSer, please see its documentation.
Note that we are hoping to migrate JIRA to Polis for user management so that full LDAP user and group management is supported. Confluence has already done so.
OpenSymphony's PropertySet is a framework that can store a set of properties (key/value pairs) against a particular "entity" with a unique id. An "entity" can be anything one wishes. For exmaple, OSUser uses PropertySet to store user's e-mail address, full name and preferences. Therefore, in case of OSUSer, the "entity" is a User.
Each property has a key (which is always a java.lang.String) and a value, which can be:
Each property is always associated with one entity. As far as PropertySet is concerned an "entity" has an entity name, and a numeric id. As long as the same entity name/id combination is used to store the value and retrieve the value, everything will work.
In JIRA PropertySet uses the following database tables:
propertyentry- records the entity name and id for a property, its key, and the data type of the property's value. Each record in this table also has a unique id.
propertystring- records String values
propertydecimal- records Double values
propertydate- records Date values
propertynumber- records Long values
Each of the records in property<type> tables also has an id column. The id is the same as the id of the propertyentry record for this property. As the property's key and value are split across 2 tables, to retrieve a property value, a join needs to be done, between propertyentry table and one of the property<type> tables. Which property<type> table to join with is determined by the value of the
propertytype column in the propertyentry record.
Here is an example of a full name stored for a user:
PropertySet is used in JIRA:
- By the OSUser framework to store users e-mail, fullname, and preferences
- To store Application Properties, which are configurable settings that a user can change to customise their installation of JIRA. For more information on Application Properties please see JIRA's documentation
- To store chosen preferences of Portlets on user's Dashboards.
JIRA Utility and Manager Classes
A lot of business logic in JIRA is implemented in 100s of java classes. The classes can be simple utility classes or Manager Objects.
Manager Objects in JIRA usually have one specific goal (or topic). For example
com.atlassian.jira.project.version.VersionManager is used to work with project versions, i.e. create, update, delete and retrieve versions.
Manager objects use a lot of external dependencies, most of which are open source, but some are developed by Atlassian and are usually shared between Atlassian products.
Since JIRA 3.7 Manager classes are generally also wrapped by a corresponding service class. The idea is that any validation of business logic necessary is carried out by the service classes whereas manager classes are responsible for actually doing the action. For instance see the ProjectService's validateCreate method and it's corresponding create method. The ProjectManager then only has a create method which will go off and create a project assuming any validation has already been carried out by the client. This allows clients to simply call the service class in order to validate and create a project, but still gives the flexibility of circumventing validation if the ProjectManager is used directly.