The basic steps to setting this option is as follows:

1. Open Thunderbird>Preference>Advanced>General>Config Editor

2. type: mail.biff.use_new_count_in_mac_dock and change setting to true

That’s all there is to it. Now your Thunderbird dock icon will only display the number of new messages since you last opened an e-mail, similar to the mail notification icon in other clients including Microsoft Outlook.

For those who have never used it before, RearViewMirror is an over-glorified version of those mirrors office workers attach to their monitors so people don’t sneak up on them. Instead of using a mirror though, it uses a webcam and allows users to share their webcams with others around the office.

Note that in version 0.9.28 of logback, there is a bug in the MS SQL schema where all the event_id fields have an invalid type of DECIMAL(40). These must be changed to DECIMAL(38). This tutorial assume the use of an MS SQL database. Other databases will work, but the triggers and schema will need to be adjusted for those dialects accordingly.

In the Shibboleth logging.xml configuration file, start by adding the following appender:

    <appender name="IDP_DB_APPENDER" class="ch.qos.logback.classic.db.DBAppender">
      <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
        <dataSource class="com.jolbox.bonecp.BoneCPDataSource">
          <driverClass>com.microsoft.sqlserver.jdbc.SQLServerDriver</driverClass>
          <jdbcUrl>jdbc:sqlserver://dbserver.example.edu:5555;databaseName=ShibAudit</jdbcUrl>
          <username>someUsername</username>
          <password>somePassword</password>
        </dataSource>
      </connectionSource>
    </appender>

Replace the database name, server, usernames and passwords respectively.

For the above example, the BoneCP connectionSource is used for connection pooling. The BoneCP libraries will be available if uApprove has been installed. Additional configuration options can be specified for tweaking connection counts and partitions within the pool.

An alternative to BoneCP is the c3p0 connection pool library. This library comes with Shibboleth and requires no extra jar files:

  <appender name="IDP_DB_APPENDER" class="ch.qos.logback.classic.db.DBAppender">
    <connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
      <dataSource class="com.mchange.v2.c3p0.ComboPooledDataSource">
        <driverClass>com.microsoft.sqlserver.jdbc.SQLServerDriver</driverClass>
        <jdbcUrl>jdbc:sqlserver://dbserver.example.edu:5555;databaseName=ShibAudit</jdbcUrl>
        <user>someUser</user>
        <password>somePassword</password>
      </dataSource>
    </connectionSource>
  </appender>

Again, replace the database name, server, usernames and passwords respectively. Next, the new appender needs to be attached to the audit logger:

    <logger name="Shibboleth-Audit" level="ALL">
        <appender-ref ref="IDP_AUDIT" />
        <appender-ref ref="IDP_DB_APPENDER" />
    </logger>

At this point, Shibboleth IDP can be restarted and attempts to authenticate with the IDP should result in log entries in the database. Make sure this is working. If not, check the idp-process.log as well as Tomcat’s cataline.out log file to determine if there were errors creating the DBAppender object.

Shibboleth 2.2.1 places its audit logs in a pipe delimited format that can easily be parsed. Rather than let the logger store this long pipe delimited string in our database, it would be beneficial to convert these logs into structure that’s easier to query. Start by creating the following table in the same database the DBAppender writes to:

CREATE TABLE audit_log (
   logtime datetime,
   remoteAddr VARCHAR(255),  
   requestbinding VARCHAR(100),
   requestId VARCHAR(50),
   relayingPartyId VARCHAR(255),
   messageProfileId VARCHAR(100),
   assertingPartyId VARCHAR(255),
   responseBinding VARCHAR(100),
   responseId VARCHAR(50),
   principalName VARCHAR(8),
   authNMethod VARCHAR(100),
   releasedAttributeIds VARCHAR(255),
   nameIdentifier VARCHAR(100),
   assertionIDs VARCHAR(100)
);

Now, a trigger will be added to the logging_event table so that whenever a row is inserted, it will be parsed and placed into the new tables.

SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO

CREATE TRIGGER [dbo].[parseLog]
   ON  [dbo].[logging_event]
   AFTER INSERT
AS 
BEGIN

	SET NOCOUNT ON;

  DECLARE @data VARCHAR(4000)
  DECLARE @xml XML
  DECLARE @unixTimestamp datetime
  
  --Convert UNIX timestamp, with ms, to mssql datetime
  SET @unixTimestamp = (SELECT dateadd(ms,CAST(RIGHT(timestmp,3) AS INT),dateadd(ss,CAST(timestmp AS BIGINT)/1000,'01/01/1970')) FROM INSERTED)
       
  --Data as XML for easy parsing
  SET @data = (SELECT formatted_message FROM INSERTED)
  SET @xml = '<Cols><Col>' + REPLACE(@data,'|','</Col><Col>') + '</Col></Cols>'    
  
  --Different Tables for different logger types
  DECLARE @type AS VARCHAR(254)
  SET @type = (SELECT logger_name FROM INSERTED)
  
  IF @type = 'Shibboleth-Audit'
  BEGIN 
	  --Fields to parse 
	   DECLARE @requestbinding AS VARCHAR(100)
	   DECLARE @requestId AS VARCHAR(50)
	   DECLARE @relayingPartyId AS VARCHAR(255)
	   DECLARE @messageProfileId AS VARCHAR(100)
	   DECLARE @assertingPartyId AS VARCHAR(255)
	   DECLARE @responseBinding AS VARCHAR(100)
	   DECLARE @responseId AS VARCHAR(50)
	   DECLARE @principalName AS VARCHAR(8)
	   DECLARE @authNMethod AS VARCHAR(100)
	   DECLARE @releasedAttributeIds AS VARCHAR(255)
	   DECLARE @nameIdentifier AS VARCHAR(100)
	   DECLARE @assertionIDs AS VARCHAR(100)
	   
	   --Store the event_id in the IP address. The event_property trigger
	   --  will replace this with the real IP
	   DECLARE @eventId AS DECIMAL(38,0)
	   SET @eventId = (SELECT event_id FROM INSERTED)

	  SELECT 
		@requestBinding = x.d.value('Col[2]', 'VARCHAR(100)'),
		@requestId = x.d.value('Col[3]', 'VARCHAR(50)'),
		@relayingPartyId = x.d.value('Col[4]', 'VARCHAR(255)'),
		@messageProfileId = x.d.value('Col[5]', 'VARCHAR(100)'),
		@assertingPartyId = x.d.value('Col[6]', 'VARCHAR(255)'),
		@responseBinding = x.d.value('Col[7]', 'VARCHAR(100)'),
		@responseId = x.d.value('Col[8]', 'VARCHAR(50)'),
		@principalName = x.d.value('Col[9]', 'VARCHAR(8)'),
		@authNMethod = x.d.value('Col[10]', 'VARCHAR(100)'),
		@releasedAttributeIds = x.d.value('Col[11]', 'VARCHAR(255)'),
		@nameIdentifier = x.d.value('Col[12]', 'VARCHAR(100)'),
		@assertionIDs = x.d.value('Col[13]', 'VARCHAR(100)')
	  FROM  @xml.nodes('/Cols') x(d)

	  INSERT INTO audit_log (logtime, remoteAddr,requestbinding,requestId,relayingPartyId,messageProfileId,assertingPArtyId,
		responseBinding,responseId,principalName,authNMethod,releasedAttributeIds, nameIdentifier, assertionIds)
		VALUES(@unixTimeStamp,@eventId, @requestBinding,@requestId,@relayingPartyId,
		@messageProfileId,@assertingPartyId,@responseBinding,@responseId,@principalName,
		@authNMethod,@releasedAttributeIds,@nameIdentifier,@assertionIDs)
  END
END
GO 

Since MS SQL has no built-in function for splitting fields on a delimiter, the above function replaces the pipe symbols with opening and closing XML tags so that MS SQL’s built-in XPath engine can be used to parse the field. A conversion must also be done to translate the UNIX timestamp to an MS SQL datetime type. Finally, the event_id is used as a placeholder in the field containing the client’s IP address. This is because by default, Shibboleth’s audit logs do not contain IP information. This can be added however using a custom servlet filter with SLF4J.

SLF4J supports a MDC which allows for values to be mapped to a logger for a given thread instance. Since only one thread in a Java servlet container is used per connection at any given time, this can be used to hold items such as the connecting client’s IP address for logging. The DBAppender inserts these properties in the logging_event_property table. A custom filter can be written to create these properties, but SLF4J comes with the MDCInsertingServletFilter which injects certain common attributes into the MDC such as user-agent, remote host, query string, etc.

In the idp.war, add the following filter to the web.xml.

  <filter>
    <filter-name>MDCInsertingServletFilter</filter-name>
    <filter-class>
      ch.qos.logback.classic.helpers.MDCInsertingServletFilter
    </filter-class>
  </filter>
  <filter-mapping>
    <filter-name>MDCInsertingServletFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

The SLF4J documentation recommended adding the MDC as the first filter, but unless attributes are needed for logging within other filters from what the MDC injects, this isn’t always necessary. For the database audit logging, the filter can be placed at the end of the idp.war‘s web.xml file.

Finally, a trigger must be added to handle the properties that are inserted, namely the remote IP address, and update the record of the original log entry.

SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO

CREATE TRIGGER [dbo].[setLogIP]
   ON  [dbo].[logging_event_property]
   AFTER INSERT
AS 
BEGIN   
   IF (SELECT mapped_key FROM INSERTED) = 'req.remoteHost'
   BEGIN   
      UPDATE audit_log  SET remoteAddr = (SELECT mapped_value FROM INSERTED)
        WHERE remoteAddr = CONVERT(varchar(255),(SELECT event_id FROM INSERTED))
   END   
END
GO

The DBAppender is transaction based, so if any triggers or query statements fail (e.g. if permissions are not setup correctly for the database user), the entire logging transaction will be rolled back and no results will appear in the database table. It is best to implement this is stages, starting with getting the DBAppender working and then adding the new table and triggers.

Since the standard text based log files do not include an IP address, it is best to include this new attribute in the original files as well. This can be done by modifying the RollingFileAppender for the audit log. The following example adds the IP address and also sets the rollover for the log file to 1 year (365 days). This should be adjusted to the retention requirements of the institution’s legal department.

    <appender name="IDP_AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>/opt/shibboleth-idp/logs/idp-audit.log</File>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <FileNamePattern>/opt/shibboleth-idp/logs/idp-audit-%d{yyyy-MM-dd}.log</FileNamePattern>
            <maxHistory>365</maxHistory>
        </rollingPolicy>

        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <charset>UTF-8</charset>
            <Pattern>%X{req.remoteHost}|%msg%n</Pattern>
        </encoder>
    </appender>

Having audit logs in a database makes it convenient to aggregate Shibboleth authentication requests for reports, as well as retrieve information quickly for legal and security requests. It is recommended to also keep the RollingFileAppender to use as a backup in case of problems with the database connection.

http://download.opensuse.org/repositories/openSUSE:/Tools/SLE_10/

You will most likely need the installation/service pack DVD mounted as well in order to install dependencies such as neon and apr. The dependencies will be pulled in automatically by running the following:

zypper install subversion

The output should look like the following:

zypper install subversion
Restoring system sources...
Parsing metadata for SUSE Linux Enterprise Server 10 SP3-20110408-123840...
Parsing metadata for -20110513-093220...
Parsing RPM database...
Summary:
<install>   [S3:0][package]neon-0.26.1-10.1.x86_64
<install>   [S2:1][package]libapr-util1-1.2.2-13.7.x86_64
<install>   [S2:1][package]libapr1-1.2.2-13.2.x86_64
<install>   [S3:0][package]subversion-1.6.16-29.2.x86_64
Continue? [y/n]: y
Downloading: [S2:1][package]libapr1-1.2.2-13.2.x86_64, 103.4 K(258.9 K unpacked)
Installing: [S2:1][package]libapr1-1.2.2-13.2.x86_64
Downloading: [S3:0][package]neon-0.26.1-10.1.x86_64, 102.6 K(311.4 K unpacked)
Installing: [S3:0][package]neon-0.26.1-10.1.x86_64
Downloading: [S2:1][package]libapr-util1-1.2.2-13.7.x86_64, 63.3 K(149.3 K unpacked)
Installing: [S2:1][package]libapr-util1-1.2.2-13.7.x86_64
Downloading: [S3:0][package]subversion-1.6.16-29.2.x86_64, 1.8 M(6.0 M unpacked)
Installing: [S3:0][package]subversion-1.6.16-29.2.x86_64

Rather than change the JAAS layer to use Novell’s LDAP API, a usable approach is to read a user’s LDAP attributes after a login to verify the password hasn’t expired and, if so, to inform the user that he or she must change that password. To do this, extend the edu.vt.middleware.ldap.auth.handler.BindAuthenticationHandler handler as seen in the following example.

public class GraceAuthenticationHandler extends BindAuthenticationHandler {
  
  protected final Log logger = LogFactory.getLog(this.getClass());

  public static final String MALFORMED_EXPIRATION_DATE = "-90555";
  
  public static final String PASSWORD_EXPIRED = "-223";
  
  public GraceAuthenticationHandler() {
  }

  public GraceAuthenticationHandler(final AuthenticatorConfig ac) {
    this.setAuthenticatorConfig(ac);
  }

  public void authenticate(final ConnectionHandler ch, final AuthenticationCriteria ac) throws NamingException {

    Ldap ldap = null;
    
    try {
        super.authenticate(ch, ac);

        ldap = new Ldap(this.config);
        
        Attributes attrs = ldap.getAttributes(ac.getDn(),new String[] { "passwordExpirationTime", "loginGraceRemaining" } );        
        
        String exp = attrs.get("passwordExpirationTime") != null ? (String) attrs.get("passwordExpirationTime").get(0) : "";
        String graceLogins = attrs.get("loginGraceRemaining") != null ? (String) attrs.get("loginGraceRemaining").get(0) : "";

        logger.debug("UserDN: " + ac.getDn() );
        logger.debug("Expiration Date: " + exp);
        logger.debug("GraceLogins: " + graceLogins);
        
        Date date;
        try {
          date = new SimpleDateFormat("yyyyMMddHHmmss").parse(exp);
        }
        catch (ParseException p) {
          throw new AuthenticationException(String.format("Error (%s): User's password expiration time is in incorrect format",MALFORMED_EXPIRATION_DATE));
        }
        
        if(date.before(new Date())) {
          throw new AuthenticationException(String.format("Error (%s): Password expired on %s. %s grace logins remaining",PASSWORD_EXPIRED,exp,graceLogins));
        }

    } catch(RuntimeException e) {
      throw e;
    } finally {
      if (ldap != null) {
        ldap.close();
      }
    }
  }

  public GraceAuthenticationHandler newInstance()
  {
    return new GraceAuthenticationHandler(this.config);
  }
}

It’s important to note that the password expired error code we are setting is the same as the Novell error code: -223. For an invalid expiration date, a number has been chosen randomly outside the range of standard Novell error codes. Typically, this error will be seen if the user specified in the login.config does not have permission to view the passwordExpirationTime and loginGraceRemaining attributes.

This custom authentication handler must be added to the login.config as seen below.

ShibUserPassAuth {

  edu.vt.middleware.ldap.jaas.LdapLoginModule required
      host="ldaps://ldap.example.edu"
      base="o=example"
      bindDn="cn=IDMUser,ou=admins,o=example"
      bindCredential="somePassword"
      ssl="true"
      userField="uid"
      subtreeSearch="true"
      authenticationHandler="edu.example.shibboleth.idm.auth.GraceAuthenticationHandler";
};

When the JAAS layer encounters this exception, it copies the message from the exception into a new LoginException. Because of this, exceptions with new custom attributes cannot be used. Instead, the error string must be parsed to determine the cause of the error. This can be done in the login.jsp found in the idp.war by adding the following:

<%@ page import="edu.example.shibboleth.idm.auth.GraceAuthenticationHandler" %>

...

<% if (request.getAttribute(LoginHandler.AUTHENTICATION_EXCEPTION_KEY) != null) {

  Exception exception = (Exception) request.getAttribute(LoginHandler.AUTHENTICATION_EXCEPTION_KEY);
  String loginMsg = exception.getMessage().trim();
  String niceMsg = "";

  String changePassUrl = "https://example.edu/changePasswordApp";

  //display error message
  if(loginMsg.contains("Cannot authenticate dn, invalid dn") || loginMsg.contains("669")) {
  niceMsg = "Invalid username or password";
  }
  else if(loginMsg.contains(GraceAuthenticationHandler.MALFORMED_EXPIRATION_DATE)) {
  niceMsg = "Cannot authenticate. Account has invalid expiration date";
  }
  else if(loginMsg.contains(GraceAuthenticationHandler.PASSWORD_EXPIRED)) {
  niceMsg = String.format("Your password has expired. Click <a href=\"%s\">here</a> to change your password",changePassUrl);
  }
  else if(loginMsg.contains("222")) {
  niceMsg = "Password has expired and you are out of grace logins. Please call the helpdesk.";
  }
  else if(loginMsg.contains("220")) {
  niceMsg = "Account is disabled";
  }
  else if(loginMsg.contains("217")) {
  niceMsg = "Number of concurrent connections exceeded";
  }
  else if(loginMsg.contains("197")) {
  niceMsg = "Account is locked";
  }
  else if(loginMsg.contains("218")) {
  niceMsg = "Login time limited";
  }
  else {
  niceMsg = "An unknown authentication error occured";
  }

%>
<span style="color:red; background-color:white; padding: 5px;"><%= niceMsg %></span>
<% } %>

The above example handles the most common Novell e-Directory error codes. It is important to note that with this example, the user is forced to change his or her password even if grace logins remain. Allowing the user to continue to authenticate after grace logins have expired would require an additional custom login servlet and possible a custom login handler.

Special thanks goes to Daniel Fisher who provided most of the code for the authentication handler, as well as the other users on the Shibboleth-dev mailing list who helped me with writing and debugging.

¹ LDAP errors returned when NDS login, password, time and address restrictions are set Novell. February 12, 2003

Update (2011.12.05): uApprove 2.3 has changed to use ANSI SQL. The default SQL configuration in uApprove 2.3 will work with Microsoft SQL, so long as the following changes are made to the schema:

CREATE TABLE AttributeReleaseConsent (
userId         VARCHAR(104)                           NOT NULL,
relyingPartyId VARCHAR(104)                           NOT NULL,
attributeId    VARCHAR(104)                           NOT NULL,
valuesHash     VARCHAR(256)                           NOT NULL,
consentDate    DATETIME NOT NULL,

PRIMARY KEY (userId, relyingPartyId, attributeId)
);

CREATE TABLE ToUAcceptance (
userId         VARCHAR(104)                           NOT NULL,
version        VARCHAR(104)                           NOT NULL,
fingerprint    VARCHAR(256)                           NOT NULL,
acceptanceDate TIMESTAMP      NOT NULL,  
 PRIMARY KEY (userId, version)
);

For Microsoft SQL, the ToUAcceptance needs to have the DEFAULT and CURRENT_TIMESTAMP attributes removed and the AttributeReleaseConsent.consentDate needs to be changed to a DATETIME. The only other thing that needs to be changed is that in the uApprove.properties file, the database.drive needs to be changed to either com.microsoft.sqlserver.jdbc.SQLServerDriver if using the Microsoft native JDBC driver or net.sourceforge.jtds.jdbc.Driver if using the open source jTDS driver. Be sure to copy either the sqljdbc4.jar or the jtds-1.2.5.jar file into all the appropriate lib directories.

That’s it! The 2.3 version of uApprove requires significantly less modification over version 2.2. For everything else, follow the standard uApprove install instructions.

The following is the original post for older version of uApprove (2.2.1):

Follow the installation instructions found on the uApprove website. There are only three major steps which need to be altered. When creating the database schema, use the following for Microsoft SQL:

create table ArpUser (
  idxArpUser bigint identity(1,1) primary key,
  auUserName varchar(255) not null,
  auLastTermsVersion varchar(255),
  auFirstAccess datetime,
  auLastAccess datetime
);
create index idxUserName on ArpUser (auUserName );

create table ShibProvider (
  idxShibProvider bigint identity(1,1) primary key,
  spProviderName varchar(255)
);

SET IDENTITY_INSERT ShibProvider On;
insert into ShibProvider (idxShibProvider) values (1);
SET IDENTITY_INSERT ShibProvider Off;
create index idxProvidername on ShibProvider (spProviderName);

create table AttrReleaseApproval (
  idxAttrReleaseApproval bigint identity(1,1) primary key,
  araIdxArpUser bigint references ArpUser ( idxArpUser ),
  araIdxShibProvider bigint references ShibProvider( idxShibProvider ),
  araTimeStamp datetime not null,
  araTermsVersion varchar(255),
  araAttributes text
);

create table ProviderAccess (
  idxProviderAccess bigint identity(1,1) primary key,
  paIdxArpUser bigint references ArpUser( idxArpUser ),
  paIdxShibProvider bigint references ShibProvider( idxShibProvider ),
  paAttributesSent text,
  paTermsVersion varchar(255),
  paIdxAttrReleaseApproval bigint references AttrReleaseApproval ( idxAttrReleaseApproval ),
  paShibHandle varchar(255),
  paTimeStamp datetime not null
);

The major differences include using MSSQL’s bigint instead of MySQL’s unsigned int, using identity(1,1) instead auto_increment, replacing the timestamp fields with datetime fields and turning off the identity for inserting the first service provider record. You will need to create a standard SQL user and give it rights to this table in SQL Management Studio. If you use an Active Directory user with windows authentication, Shibboleth must be running on a Windows server and you’ll have to use the native authentication dll. Since I preformed this installation on Linux, that setup is outside the scope of this tutorial.

Next, you’ll notice in the uApprove documentation that all the SQL commands are stored in a mysql.commands file. Create a microsoftSQL.commands file and place the following in it:

selGlobalShibProvider = select idxShibProvider as idx from ShibProvider where spProviderName is null

selIdxUser = select idxArpUser as idxUser from ArpUser where auUserName = '?'

selShibProvider = select idxShibProvider as idxProvider from ShibProvider where spProviderName = '?'

insShibProvider = insert into ShibProvider (spProviderName) values ( '?' )

selArpInfoByUsername1 = select idxArpUser as idxUser, convert(varchar,araTimeStamp,20) as ArpDate, araTermsVersion as TermsOfUseManager, araAttributes as Attributes, spProviderName as ShibProvider from ArpUser, AttrReleaseApproval, ShibProvider where auUserName='?' and idxArpUser=araIdxArpUser and araIdxShibProvider = idxShibProvider order by araTimeStamp desc

selArpInfoByUsername2 = select idxArpUser as idxUser, auLastTermsVersion as TermsOfUseManager, auLastAccess as ArpDate from ArpUser where auUserName='?'

insUser = insert into ArpUser (auUserName, auLastTermsVersion, auFirstAccess, auLastAccess ) values ( '?', '?', getdate(), getdate() )

updUser = update ArpUser set auLastTermsVersion = '?', auFirstAccess=auFirstAccess, auLastAccess=getdate() where auUsername = '?'
updUser1 = update ArpUser set auFirstAccess = auFirstAccess, auLastAccess = getdate() where auUserName = '?'

selGlobalArp = select count(*) as cnt from AttrReleaseApproval, ArpUser, ShibProvider where idxArpUser=araIdxArpUser and idxShibProvider = araIdxShibProvider and spProviderName is null and auUserName = '?'

insAttrApproval = insert into AttrReleaseApproval ( araIdxArpUser, araIdxShibProvider, araTimeStamp , araTermsVersion,araAttributes ) values ( ?, ?, getdate() , '?', null )

insAttrApproval1 = insert into AttrReleaseApproval (araIdxArpUser, araIdxShibProvider, araTimeStamp, araTermsVersion, araAttributes ) values ( ?, ?, getdate() , '?', '?' )

delAttrApproval = delete from AttrReleaseApproval where araIdxArpUser = ? and araIdxShibProvider = ?

updAttrApproval = update AttrReleaseApproval set araTermsVersion = '?', araAttributes = '?' where araIdxArpUser = ? and araIdxShibProvider = ?

selIdxAttrApproval = select idxAttrReleaseApproval as idxApproval, araIdxArpUser as IdxUser, araIdxShibProvider as idxProvider, araTermsVersion as TermsVersion, araAttributes as Attributes from ArpUser, AttrReleaseApproval, ShibProvider where auUserName='?' and idxArpUser=araIdxArpUser and spProviderName = '?' and araIdxShibProvider = idxShibProvider order by araTimeStamp desc

selIdxAttrApprovalGlobal = select idxAttrReleaseApproval as idxApproval, araIdxArpUser as IdxUser, araIdxShibProvider as idxProvider, araTermsVersion as TermsVersion, araAttributes as Attributes from ArpUser, AttrReleaseApproval, ShibProvider where auUserName='?' and idxArpUser=araIdxArpUser and spProviderName is null and araIdxShibProvider = idxShibProvider order by araTimeStamp desc

insProviderAccess = insert into ProviderAccess ( paIdxArpUser, paIdxShibProvider, paTermsVersion, paAttributesSent, paIdxAttrReleaseApproval, paTimeStamp ) values ( ?, ?, '?', '?', ?, getdate() )

selIdxProviderAccess = select idxProviderAccess as idxPA from ProviderAccess, AttrReleaseApproval where paIdxAttrReleaseApproval=idxAttrReleaseApproval and araIdxArpUser=?

clearReleaseForAccess = update ProviderAccess set paIdxAttrReleaseApproval = NULL, paTimeStamp = paTimeStamp where paIdxArpUser = ?

delAttrReleaseApprovals = delete from AttrReleaseApproval where araIdxArpUser = ?

The primary differences include replacing MySQL’s now function with get_date and replacing the date_format with convert. In MySQL, fields that assumed the current time when inserted with nulls must explicitly define the field and use the get_date function in MSSQL.

The database.properties file must be changed to use the new MSSQL command file like so:

sqlCommands=/opt/uApprove/conf/microsoftSQL.commands

driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
url=jdbc:sqlserver://<hostname>:<port>;databaseName=uApprove;intergratedSecurity=true
user=<insert user>
password=<insert password>

The version 3 JDBC drivers for MSSQL can be found on the Microsoft website at the following address:

http://www.microsoft.com/downloads/en/details.aspx?FamilyID=%20a737000d-68d0-4531-b65d-da0f2a735707&displaylang=en

There are two jars in this package and you will only need one of them. For this installation which was for Tomcat 5 running on Java 1.6, I used sqljdbc4.jar. This jar needs to be added everywhere there is a mysql-connector.jar. This includes uApprove-2.2.1/idp-plugin-2.2.1/lib, uApprove-2.2.1/viewer-2.2.1/webapp/WEB-INF/lib and even the shibboleth-idp/war/idp.war. The idp.war is redeployed in the uApprove install instructions. You can add it before this point or add it manually to the jar’s WEB-INF/lib folder afterwords.

That should be all that is necessary to run the uApprove plug-in against Microsoft SQL Server. I’ve tested this in MSSQL 2005 but it should run fine on 2008 as well. If you run into issues, be sure to check the log files for uApprove, Shibboleth and Tomcat to help diagnose issues.

Password Security

How can someone gain access to your e-mail account without knowing your password? Have you ever signed up for a new website or service you wanted to try out? Did you give them your e-mail address during registration? Did you use the same password you used for your e-mail account?

Newer websites and services that haven’t been globally trusted may be scraping your passwords during registration and testing them against the e-mail account you provided. Once gaining access, it’s easy to scan e-mail for messages from other services and begin requesting access to other accounts associated with it.

You may have also registered with a new website or web service that is not necessarily malicious. They may just be storing your password insecurely and unencrypted. A potential hacker may have discovered a security exploit allowing them to access that password data.

The solution isn’t to simply use only trusted sites. Using new services and trying new concepts is what helps the Internet grow. Plus, even large trusted services can have their security compromised by badly written code allowing third parties to gain access to your data. The better solution is to use unique password for every website. How would you remember a unique password for every website? You’d use a password algorithm.

Password Algorithms

Many Internet users typically use the same password for multiple systems. Some people use a slightly more secure technique of having different levels of passwords. They may use one for unsecured sites, such as social networking or instant messaging, another for secure sites such as e-mail and a very strong one for computer and bank passwords. Although this is better than using the same password everywhere, it’s not replacement for the security provided by a unique password algorithm.

A good password algorithms can be based off the website the password is intended for. For instance, you can take the first or last letter of the website, combine it with a pin number or short password, and then tack on a character representing something else about the site. For example, you could add a letter representing the top level domain (e.g. The letter ‘A’ for .com, ‘S’ for .net, ‘D’ for .org and ‘F’ for others).

You could also use something on the site itself, like the company’s primary color or the background color of the website. Although using something on the page itself may change over time, this may also force you to continually change and rotate out passwords.

You can be creative and find many different ways to create a good password system. However there are a few basic rules you should try to follow to ensure good password selections.

• Make sure your pattern will always give you a password with at least one capital letter, one lowercase letter and one number
• Ensure your system always gives you a password between 8 and 9 characters long. Many websites have restrictions on length and 8 or 9 characters ensures your password will never be too short or two long
• Avoid special characters. Many websites ban these (due to ignorance) for security and it’s much more difficult to remember exceptions to your password system.
• Chose a system you can remember easily, but that’s not easy to understand should someone get a hold of one of your passwords.

In addition to individual passwords for each website, you should also have secure passwords for non-web related systems such as company computers/networks and home computers.

You don’t need to change every password at once when you come up with an algorithm. Just start changing passwords as you access sites you use more frequently. Whenever you access a website with your old password, go into that website’s account options and change it. You can then gradually adjust to a new password algorithm over the course of a few weeks.

Additional Tips

• Never use your web browser’s password store to remember passwords for you. Turn it off, remember your password system and commit them to memory.
• Always remember to log-off your accounts on computers that are not yours or that you cannot secure.

Security Questions

One serious piece of contention in the network security industry are the increasing use of security questions. Although they are used to alleviate customer services calls, the questions themselves are easily guessable.

In an 2009 IEEE Symposium on Security and Privacy, researchers from Microsoft and Carnegie Mellon University showed that in a study involving 130 people, 28% of the people who were known and trusted by the studies participants could guess the correct answers to participants’ security questions. Even people not trusted still had a 17% chance of guessing a participant’s answers¹.

Some security experts suggest typing in random letters for security questions, going through the additional burden of calling the company should one’s user account become locked. Others suggest using a similar password algorithm as described above to generate a separate password for the security question. Without doing one or the other, the system a user is accessing gains an automatic backdoor to his or her account, defeating the purpose of having password based security in the first place.

A better solution to using security questions is to use reset codes sent to user’s e-mail addresses, or combining an e-mailed reset code with both security questions and locking an account after several bad attempts. While this is a better solution, many websites cannot implement these e-mail based password reset systems because they allow multiple accounts to use the same e-mail address.

Authentication without Password

Another item to watch out for are services which ask for a password to another services. For example, a new social networking site that may ask for your e-mail password in order to search for friends that might be using the new service. While at one time this was the only way for third parties to access information on your account, it isn’t any longer.
Now almost all major services support some type of single sign-on authentication. Twitter uses an OAuth based system, Facebook has their own Facebook Connect system, Microsoft has LiveID and Google has third party account authentication. These systems work by directing you to a given service (Facebook, Twitter, Google, etc.) with a security token. On that site, you log-in and authorize the token granting the other website limited access to your account.

The advantage of this system is that if the 3rd party service does start doing something malicious, such as sending spam messages to your contacts, you can simply revoke the applications access to your account without having to change any passwords. Most services even allow their users to report malicious applications, which could cause their application tokens to be rejected permanently for all users.

Conclusions

Password security is critical in a world where so much of your personal information an accounts can be accessed electronically. Developing and protecting a good password system is more important in many ways than defending your social security number.

At a minimum, you should have different levels of passwords: An insecure password for social networking websites and other trivial services, a high security password for e-mail, payment accounts and other high security services, and finally an ultra secure password for critical websites such as on-line banking.

Ideally, you should create a password algorithm for all web passwords. Algorithms should always generate 8 to 9 character passwords that include at least one capital letter and one number, and the system should be easy to remember yet difficult to understand should one or more password become compromised.

If a user suspects a malicious website or application has gained access to one of his or her accounts, the user should change the password on that account immediately. Using an algorithm for generating passwords ensures that other accounts won’t be comprised. Without it, a user may have to change password on several websites afterwords.

Switching to a password system from a single universal password may seem a bit cumbersome, but the transition is a lot easier than one would anticipate. I switched from a set of three passwords to an algorithm three years ago and now have a much greater degree of confidence about the security of my information.

¹ Are Your Secret Questions Too Easily Answered?. Lemons. Technology Review. May 18, 2009.

public class  MyServiceBean {

    public void startProcess() {
    
        DataSource ds = (DataSource) new InitialContext().lookup("jdbc/ds1");
        con = ds.getConnection();
        
        //do something with connection        
    }    
}

The DataSource is simply an interface which the underlying application container implements in order to allow applications to get connections. In this way, a web application server can control the way connections are handed out as well as keep connections in a pool to be reused. The information about the data source, including the driver, host name, user name, password and database name are all setup on the web application server. The way they’re configured varies depending on the server (most have a web administration console or XML configuration files), but all application servers provide an initial context containing references to these data sources for all running web applications.

If we simply tired to test this bean using a main function in its own stand-alone application like so:

public static void main(String[] args) {        
    MyServiceBean b = new MyServiceBean();
    b.startProcess();              
}

We would get the following exception:

javax.naming.NoInitialContextException: Need to specify class name in environment or system property, or as an applet parameter, or in an application resource file:  java.naming.factory.initial
	at javax.naming.spi.NamingManager.getInitialContext(Unknown Source)
        .....

In order to run code which looks up a DataSource this way in a stand-alone application, we must create our own implementation of a DataSource object as well as an InitialContextFactory, plus several intermediary objects, and then tell our currently running JRE to use our context object for all subsequent calls to new InitialContext(). Because we’re running locally, we don’t need to implement everything out of all these interfaces, just the bare minimum in order to provide DataSource and Connection objects.

First, we’ll look at a very quick and dirty solution. In this solution, we declare new classes directly within the main function using the final keyword and hard-coding the driver and connection strings. This is a quick drop to simply test a single bean.

public static void main(String[] args) throws SQLException, ClassNotFoundException, NamingException
{
    final class LocalDataSource implements DataSource , Serializable {

            private String connectionString;
            private String username;
            private String password;
            
            LocalDataSource(String connectionString, String username, String password) {
                this.connectionString = connectionString;
                this.username = username;
                this.password = password;
            }
            
            public Connection getConnection() throws SQLException
            {
                return DriverManager.getConnection(connectionString, username, password);
            }
    
            public Connection getConnection(String arg0, String arg1)
                    throws SQLException
            {
                return getConnection();              
            }
    
            public PrintWriter getLogWriter() throws SQLException
            {
                return null;
            }
    
            public int getLoginTimeout() throws SQLException
            {
                return 0;
            }
    
            public void setLogWriter(PrintWriter out) throws SQLException {}
    
            public void setLoginTimeout(int seconds) throws SQLException {}

    }
    
    final class DatabaseContext extends InitialContext {

        DatabaseContext() throws NamingException {}

        @Override
        public Object lookup(String name) throws NamingException
        {
            try {
                //our connection strings
                Class.forName("com.mysql.jdbc.Driver");
                DataSource ds1 = new LocalDataSource("jdbc:mysql://dbserver1/dboneA", "username", "xxxpass");
                DataSource ds2 = new LocalDataSource("jdbc:mysql://dbserver1/dboneB", "username", "xxxpass");

                Properties prop = new Properties();
                prop.put("jdbc/ds1", ds1);
                prop.put("jdbc/ds2", ds2);
                
                Object value = prop.get(name);
                return (value != null) ? value : super.lookup(name);
            }
             catch(Exception e) {
                 System.err.println("Lookup Problem " + e.getMessage());
                 e.printStackTrace();
             }  
             return null;            
        }        
        
    }

    final class DatabaseContextFactory implements  InitialContextFactory, InitialContextFactoryBuilder {

        public Context getInitialContext(Hashtable<?, ?> environment)
                throws NamingException
        {
            return new DatabaseContext();
        }

        public InitialContextFactory createInitialContextFactory(
                Hashtable<?, ?> environment) throws NamingException
        {
            return new DatabaseContextFactory();
        }
        
    }
    
    NamingManager.setInitialContextFactoryBuilder(new DatabaseContextFactory());   

    MyServiceBean b = new MyServiceBean();
    b.startProcess();
}

In this example we’ll start from the bottom. Before we run our bean we see a call to NamingManager.setInitialContextFactoryBuilder(). This function sets the factory that will be called in our environment by all subsequent calls to new InitialContext() throughout our application. Underneath the hood of a web application server, this is one of the many things that happens well before a web application is loaded.

The DatabaseContextFactory is a class we create that not only serves as a ContextFacotry but also a ContextFactoryBuilder through appropriate interfaces. Thanks to interfaces, we can simplify these two functionalities into a single class. It’s sole purpose is to return a DatabaseContext.

The DatabaseContext extends a regular InitialContext and we simply override the one function typically used by web server code, the lookup() function. It is here we can inject our own LocalDataSource objects, which return our Connection objects. On an actual web application server, the DataSource object would typically have some type of pooling mechanism that could return existing connections into a queue once the web application calls the close() function on them.

Although is is a decent quick solution, it’s really unclean and isn’t reusable without copying and pasting. It also ignores any environment parameters passed into the InitialContext and discards them. For a more permanent solution, each of the classes should be separated out and compatibility should be maintained with the environment properties passed in to our custom Context object.

For our clean and reusable solution, we’re only going to have one class with public visibility. It’s our factory class. All other classes will have default/package visibility because they shouldn’t be instantiated independently outside of our factory. Let’s start with the factory:

package org.penguindreams.db.local;

import java.util.HashMap;
import java.util.Hashtable;
import java.util.Map;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.naming.spi.InitialContextFactory;
import javax.naming.spi.InitialContextFactoryBuilder;

public class LocalContextFactory {
	/**
	 * do not instantiate this class directly. Use the factory method.
	 */
	private LocalContextFactory() {}
	
	public static LocalContext createLocalContext(String databaseDriver) throws SimpleException {

		try { 
			LocalContext ctx = new LocalContext();
			Class.forName(databaseDriver);	
			NamingManager.setInitialContextFactoryBuilder(ctx); 			
			return ctx;
		}
		catch(Exception e) {
			throw new SimpleException("Error Initializing Context: " + e.getMessage(),e);
		}
	}	
}

In the above code, we’re creating a new LocalContext. We’re also initializing our JDBC driver. As with the previous example, the NamingManager.setInitialContextFactoryBuilder function ensures the new context we’re creating will be given to all subsequent calls made to new InitialContext(). Also, as with the previous example, the LocalContext takes both the role of an InitialContextFactory and an InitialContextFactoryBuilder through the use of interfaces.

package org.penguindreams.db.local;

import java.util.HashMap;
import java.util.Hashtable;
import java.util.Map;

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.naming.spi.InitialContextFactory;
import javax.naming.spi.InitialContextFactoryBuilder;

class LocalContext extends InitialContext implements InitialContextFactoryBuilder, InitialContextFactory {

	Map<Object,Object> dataSources;
	
	LocalContext() throws NamingException {
		super();
		dataSources = new HashMap<Object,Object>();
	}
	
	public void addDataSource(String name, String connectionString, String username, String password) {
		this.
		dataSources.put(name, new LocalDataSource(connectionString,username,password));
	}

	public InitialContextFactory createInitialContextFactory(
			Hashtable<?, ?> hsh) throws NamingException {
		dataSources.putAll(hsh);
		return this;
	}

	public Context getInitialContext(Hashtable<?, ?> arg0)
			throws NamingException {
		return this;
	}

	@Override
	public Object lookup(String name) throws NamingException {
		Object ret = dataSources.get(name);
		return (ret != null) ? ret : super.lookup(name);
	}	
}

In the above example, we also see that we’ve allowed for some default behavior. For instance, properties that are given to initialize our LocalContext are stored in our local HashMap. If a lookup fails, we call the parent’s lookup method as well. The important function we add above is the addDataSource() method which creates new LocalDataSource to be looked up by the passed in name argument. Finally we have the LocalDataSource itself.

package org.penguindreams.db.local;

import java.io.PrintWriter;
import java.io.Serializable;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

import javax.sql.DataSource;

class LocalDataSource implements DataSource , Serializable {
	
	private String connectionString;
    private String username;
    private String password;
    
    LocalDataSource(String connectionString, String username, String password) {
        this.connectionString = connectionString;
        this.username = username;
        this.password = password;
    }
    
    public Connection getConnection() throws SQLException
    {
        return DriverManager.getConnection(connectionString, username, password);
    }

	public Connection getConnection(String username, String password)
			throws SQLException {return null;}
	public PrintWriter getLogWriter() throws SQLException {return null;}
	public int getLoginTimeout() throws SQLException {return 0;}
	public void setLogWriter(PrintWriter out) throws SQLException {	}
	public void setLoginTimeout(int seconds) throws SQLException {}
}

As you can see, many of the functions for the DataSource have been left unimplemented. We’ve only implemented enough functionality to get lookups working and to create simple, non-pooled connections for the end client. So our main function should now look something like the following:

public static void main(String[] args) {        
    
    LocalContext ctx = LocalContextFactory.createLocalContext("com.mysql.jdbc.Driver");
    ctx.addDataSource("jdbc/js1","jdbc:mysql://dbserver1/dboneA", "username", "xxxpass");
    ctx.addDataSource("jdbc/js2","jdbc:mysql://dbserver1/dboneB", "username", "xxxpass");
    
    MyServiceBean b = new MyServiceBean();
    b.startProcess();              
}

The call to LocalContextFactory.createLocalContext() initializes our environment with the LocalContext as the InitialContext. Then we can add the DataSource objects we need later using the addDataSource() method. All of our data objects are kept within their own packages and have limited visibility to ensure they can only be instantiated and fully initialized using the factory method.

There are some limitations to this clean implementation. For one, you can only use one type of database depending on what driver you specify with the LocalContextFactory. Also, not all of the DataSource methods are fully implemented, so you may run into problems in environments that depend on other functions and more complex implementations.

Still, the above code will work in a testing environment and, in a pinch, you can use the final classes used at the beginning of this tutorial directly in a main function for some quick and dirty testing. If you need a more complete implementation, the clean version of the code is an excellent starting point to begin building a full local implementation of your own custom DataSource objects.

Our web.xml for our WAR file is fairly basic. It contains a single servlet and a mapping to that servlet.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>SimpleRest</display-name>
   
  <servlet>
  	<servlet-name>RestService</servlet-name>
  	<servlet-class>org.penguindreams.service.ServiceHandler</servlet-class>
  </servlet>
  
  <servlet-mapping>
	<servlet-name>RestService</servlet-name> 
	<url-pattern>/models/*</url-pattern>
  </servlet-mapping>	
	
</web-app>

Likewise, our application.xml, which is used to build an EAR file which can contain multiple WAR files, is very basic. We see it only contains support for one web module.

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:application="http://java.sun.com/xml/ns/javaee/application_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd" id="Application_ID" version="5">
  <display-name>SimpleRestEAR</display-name>
  <module>
    <web>
      <web-uri>SimpleRest.war</web-uri>
      <context-root>rest</context-root>
    </web>
  </module>
</application>

Our servlet overrides the doGet method, sets the current time as an attribute and then passes on control to a JSP to finish processing the request.

public class ServiceHandler extends HttpServlet {
	
	@Override
	protected void doGet(HttpServletRequest request, HttpServletResponse response)  { 		
		try {			
			request.setAttribute("timeStamp", new Date().getTime() );			
			getServletConfig().getServletContext().getRequestDispatcher("/hello.jsp").forward(request,response);			
		} catch (Exception e) {
			System.err.println("Fatal Servlet Error");
			e.printStackTrace();
		}			
	}
	
}

Likewise, our JSP page is very simple. It just displays a header image and the resulting time.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html  xmlns="http://www.w3.org/1999/xhtml" dir="ltr" >
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
	<title>Sample Page</title>
</head>
<body>
	<p>
		<img src="images/penguindreams.gif" alt="PenguinDreams" />
		<br />
		TimeStamp: <%= request.getAttribute("timeStamp") %>
	</p>
</body>
</html>

So now that we have our application out of the way, let’s focus on the building process. The first part of the build.xml contains our variables. The sample application is built for JBoss. Depending on your web application server, the paths and variable names should be adjusted. Notice we’re pulling in both the jar libraries within our web application as well as the libraries found on the application server itself.

Eclipse does this automatically when you specify a server runtime. When building from an ant file, these libraries need to be specified for the build to complete. Be careful not to include libraries in your local lib folder that are all ready present on the application server (i.e. JSF libraries, Servlet API, Struts, log4j, et cetera). This could cause complications. For instance, deploying a WAR that contains a log4j.jar within it will cause the logging handlers within JBoss to stop working for your web application.

    <property name="build" value="./build" />
    <property name="dist" value="./dist" />
    <property name="conf"  value="./conf" />
    <property name="src"   value="./src" />
    <property name="lib"   value="./lib" />
    <property name="web"   value="./web" />
    <property name="version" value="0.1" />
    <property name="jbossLocation" value="/Users/myhomedir/jboss-6.0.0.M1/" />
    <property name="servletLib" value="${jbossLocation}/common/lib" />
    <property name="deployDir" value="${jbossLocation}/server/default/deploy/" />
    <property name="warFile" value="${dist}/${ant.project.name}.war" />
    <property name="earFile" value="${dist}/${ant.project.name}-${version}.ear" />

    <path id="build.classpath">
	<fileset dir="${lib}" includes="**/*.jar" />
	<fileset dir="${servletLib}" includes="**/*.jar" />
    </path>

We need to create some simple cleanup and initialization targets to clear out old bytecode as well as setup our build environment. The compile task will depend on the initialization being complete and make use of the libraries we specified above.

    <target name="clean">
    	<delete dir="${build}" />
    	<delete dir="${dist}" />
    </target>

    <target name="init">
    	<tstamp />
    	<mkdir dir="${build}" />
    	<mkdir dir="${dist}" />
    </target>
    
    <target name="compile" depends="init">
	<javac srcdir="${src}" destdir="${build}" optimize="on">
	    <classpath refid="build.classpath" />
	</javac>
    </target>

The WAR file task is simply an extension of the ZIP file task that places certain types of files within the correct location of the WAR file. Here we specify our web.xml configuration file, our Java classes, the web application libraries and the static content.

    <target name="war" depends="compile">
    	<war destfile="${dist}/${ant.project.name}.war" webxml="${conf}/web.xml">
    	  <lib dir="${lib}" />
    	  <classes dir="${build}"/>
    	  <zipfileset dir="${web}"  /> 
    	</war>
    </target>

The resulting JAR file has the following structure:

META-INF/
META-INF/MANIFEST.MF
WEB-INF/
WEB-INF/web.xml
WEB-INF/lib/
WEB-INF/classes/
WEB-INF/classes/org/
WEB-INF/classes/org/penguindreams/
WEB-INF/classes/org/penguindreams/service/
WEB-INF/classes/org/penguindreams/service/ServiceHandler.class
images/
hello.jsp
images/penguindreams.gif

An EAR file is also very simple. It’s just a collection of WAR files with an XML describing each individual web module and it’s Context Root. For this example, there is only one web module.

    <target name="ear" depends="war">
    	<ear destfile="${dist}/${ant.project.name}-${version}.ear" appxml="${conf}/application.xml">
    		<fileset dir="${dist}" includes="*.war" />
    	</ear>
    </target>

Finally, we have a deployment task. Most application servers can be configured to monitor a deployment directory and automatically install EAR files copied into that directory. If your application server is on a different machine than your build environment, you may need to use a remote deployment task, such as those included with IBM WebSphere to deploy EAR files using either their SOAP or RMI protocols. For this example, our server is on the same machine, so we can do a simple copy:

    <target name="deploy" depends="ear">
    	<copy todir="${deployDir}">
    		<fileset dir="${dist}" includes="*.ear" />
    	</copy>
    </target>

So our final build.xml is shown below. Notice the project root element where we specify the project name as well as the default task to run.

<?xml version="1.0"?>
<project name="SimpleRest" basedir="." default="ear">

	<property name="build" value="./build" />
	<property name="dist" value="./dist" />
	<property name="conf"  value="./conf" />
	<property name="src"   value="./src" />
	<property name="lib"   value="./lib" />
	<property name="web"   value="./web" />
	<property name="version" value="0.1" />
	<property name="jbossLocation" value="/Users/myhomedir/jboss-6.0.0.M1/" />
	<property name="servletLib" value="${jbossLocation}/common/lib" />
	<property name="deployDir" value="${jbossLocation}/server/default/deploy/" />
	<property name="warFile" value="${dist}/${ant.project.name}.war" />
	<property name="earFile" value="${dist}/${ant.project.name}-${version}.ear" />
	
	<path id="build.classpath">
		<fileset dir="${lib}" includes="**/*.jar" />
		<fileset dir="${servletLib}" includes="**/*.jar" />
	</path>
	
	<target name="clean">
		<delete dir="${build}" />
		<delete dir="${dist}" />
	</target>
	
	<target name="init">
		<tstamp />
		<mkdir dir="${build}" />
		<mkdir dir="${dist}" />
	</target>
	
	<target name="compile" depends="init">
		<javac srcdir="${src}" destdir="${build}" optimize="on">
			<classpath refid="build.classpath" />
		</javac>
	</target>
	
	<target name="war" depends="compile">
		<war destfile="${dist}/${ant.project.name}.war" webxml="${conf}/web.xml">
		  <lib dir="${lib}" />
		  <classes dir="${build}"/>
		  <zipfileset dir="${web}"  /> 
		</war>
	</target>
	
	<target name="ear" depends="war">
		<ear destfile="${dist}/${ant.project.name}-${version}.ear" appxml="${conf}/application.xml">
			<fileset dir="${dist}" includes="*.war" />
		</ear>
	</target>
	
	<target name="deploy" depends="ear">
		<copy todir="${deployDir}">
			<fileset dir="${dist}" includes="*.ear" />
		</copy>
	</target>
</project>

We now have a complete project that can be built and deployed using a simple ant command. If you prefer to deploy your project within Eclipse, you can go to Project>Properties and then select Builders and New to create a new Ant Builder. Once it is configured, preforming a build within Eclipse will launch an external delegate to run the build.xml file. Here is the output from running the deploy task.

$ ant deploy
Buildfile: build.xml

init:
    [mkdir] Created dir: /Users/myhomedir/Documents/workspace/SimpleRest/build
    [mkdir] Created dir: /Users/myhomedir/Documents/workspace/SimpleRest/dist

compile:
    [javac] Compiling 1 source file to /Users/myhomedir/Documents/workspace/SimpleRest/build

war:
      [war] Building war: /Users/myhomedir/Documents/workspace/SimpleRest/dist/SimpleRest.war

ear:
      [ear] Building ear: /Users/myhomedir/Documents/workspace/SimpleRest/dist/SimpleRest-0.1.ear

deploy:
     [copy] Copying 1 file to /Users/myhomedir/jboss-6.0.0.M1/server/default/deploy

BUILD SUCCESSFUL
Total time: 1 second

Immediately afterward, we can see JBoss pickup the new EAR file by watching its log file.

01:58:53,696 INFO  [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
01:58:53,743 INFO  [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
01:58:53,759 INFO  [AbstractServer] JBossAS [6.0.0.M1 (build: SVNTag=JBoss_6_0_0_M1 date=200912040958)] Started in 34s:58ms
01:59:05,970 INFO  [TomcatDeployment] undeploy, ctxPath=/rest
01:59:06,231 INFO  [TomcatDeployment] deploy, ctxPath=/rest

Finally, we can open a web browser, open the appropriate URL to our servlet as determined by both the application.xml and the web.xml.

Creating a web application with an ant build file is just the beginning. The build.xml can be modified with additional variables and tasks to assist in deploying web applications to different environments or for running automated unit tests prior to deployment. Variables defined within the build file can be overwritten using the -D command line option for ant. Scripts can be created on UNIX servers to automatically retrieve your projects from a source control system such as CVS, Subversion or Mercurial and run the ant script within the project with a particular set of arguments based on the environment (e.g. development, test and production).

Using ant to build projects is essential to streamlining development of J2EE web application and ensures consistency in builds and deployments. This tutorial just scratches the surface of building J2EE applications and is part of a series of tutorials for building solid enterprise services and web applications from the ground up. The full source code for the example application shown above can be downloaded as j2ee-ant-example-penguindreams.tar.bz2 or j2ee-ant-example-penguindreams.zip

try {
    sendMail(from,to,subject,body);
}
catch(AddressException e) {
    //Handle This Exception 
}
catch(UnknownHostException e) {
    //Handle This Exception
}
catch(MessagingException e) {
    //Handle This Exception
}

In some projects I would often catch the base exception class and use the instanceof keyword to clean up the exception handling as seen below. Although the code for this technique may be cleaner, it’s more difficult to add new exception types that may be introduced later by code changes:

String error = "";
try {
    sendMail(from,to,subject,body);
}
catch(Exception x) {

    error = "Internal Error: ";

    if(x instanceof AddressException) {
            error += "Invalid Internal Address";
    }
    else if(x instanceof UnknownHostException) {
            error += "Could Not Find Mail Server";
    }
    else if(x instanceof MessagingException) {
            error += "Messaging Problem";
    }
    else {
           error += "Unexpected: " + x.getMesssage();
    }
}

In both instances, programmers typically just log the exception and display a general error to the end user. Catching the individual exception types doesn’t really help in any meaningful way. Also, the exception message itself is often human readable and a clear indication of what error occurred. In my current projects, I use a base exception class and simply place any code that produces checked exceptions within a large try block and rethrow any exceptions as a property of my base exception class.

public class SimpleException extends Exception {

	private Throwable nestedException;
	
	public SimpleException(String s) {
		super(s);
	}
	
	public SimpleException(String s, Exception nestedException) {
		super(s);
		this.nestedException = nestedException;		
	}
	
	public Throwable getNestedException() {
		return this.nestedException;
	}
	
} 

Using this class, the previous example would change to the following:

String error = "";
try {
    sendMail(from,to,subject,body);
}
catch(Exception e) {
    throw new SimpleException("Error Occurred Sending E-mail",e);
}

This cleans up our code significantly. Under the old model, say that the implementation changed and new potential exceptions could possibly be thrown. Each one of those exceptions would have to be added to the throws clause to the appropriate function. If the class implemented a interface or extended and abstract class, those base methods would have to change as well, along with any code implementing the class. If we throw only one type of exception that wraps all other exceptions, we never have to worry about the method signature changing.

Some programmers may oppose this approach and classify it as an anti-pattern, similar to wrapping all checked exceptions in blocks that rethrow runtime exceptions. However, in my experience in working with large projects, using this approach is much cleaner and more maintainable. Furthermore, it allows Aspect Orientated Programming (AOP) interceptors to have a lot more information when dealing with exceptions.

This article is the first in a series of tutorials on J2EE development. The use of the except pattern I’ve used will be further expanded with seeing how it can integrate into web applications using Spring and AOP.