The raygun4java provider

Raygun4java is a library that you can easily add to your Java application, which will then allow you to transmit all exceptions to your Raygun.io dashboard. Installation is painless, and configuring your site to transmit errors takes only 5 minutes.

Raygun4java supports Java 6 and greater. The library is available as a Maven package, so you only need to add the appropriate entry to your pom.xml. JARs are also available for other build systems.

What Java project types are supported?

Pretty much anything! Classical desktop and console apps are supported by the main library. Web applications projects, such as Java Servlets and projects that use JSPs are fully supported by including the additional raygun4java-web library. This can also be used in popular web frameworks such as Spring.

First-class Scala and the Play 2 framework support is also available, and the library can also be used in code running on Google App Engine.

What can I send to Raygun.io?

Raygun4Java is designed to send any object that inherits from Throwable. You can add a set of tags (as an array of strings) to identify a certain type of message, or add a custom user data (as a key-value Map).

What are the steps I need to take to add raygun4java to my application?

Here's an overview:

  1. Add the dependency to your pom.xml, or copy the JAR(s) into a /lib folder and add it to the build path
  2. Create an exception handler and subscribe to it
  3. Add two lines to this handler - one creating an instance of RaygunClient, and the other calling Send() on it. And you're done!

Read the step-by-step instructions below.

Installation

With Maven and Eclipse/another IDE

These instructions assume you have a Maven project with a POM file set up in Eclipse, but this is also applicable to other IDEs and environments.

  1. Open your project's pom.xml in Eclipse. Click on Dependencies -> Add. In the pattern search box, type com.mindscapehq.
  2. Add com.mindscape.raygun4java and com.mindscapehq.core, version 1.3.2.

    If you are working in a web environment, add com.mindscapehq.webprovider jar too.

    If you wish to grab the example project, you can also get the sampleapp jar.

  3. Save your POM, and the dependencies should appear in Maven Dependencies.

With Maven and a command shell

If you are in a shell/text editor environment, you can run mvn install from the directory containing your project's pom.xml. The pom.xml will need to contain something like:

<dependencies>
    ...
    <dependency>
        <groupId>com.mindscapehq</groupId>
        <artifactId>raygun4java</artifactId>
        <type>pom</type>
        <version>1.3.2</version>
    </dependency>
    <dependency>
        <groupId>com.mindscapehq</groupId>
        <artifactId>core</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

POM for Web Projects

If you're using servlets, JSPs or similar, you'll need to also add:

<dependency>
    <groupId>com.mindscapehq</groupId>
    <artifactId>webprovider</artifactId>
    <version>1.3.2</version>
</dependency>

With Ant or other build tools

Download the JARs for the latest version from here:

raygun-core: required

raygun-webprovider: optional - if you want to receive HTTP request data from JSPs, servlets, GAE, web frameworks etc.

gson: required - you will also need the Gson dependency in your classpath.

Usage

Desktop applications

To catch all exceptions in your application, and to send them to Raygun:

public class MyApp
{
    public static void main(String[] args) throws Throwable
    {
            Thread.setDefaultUncaughtExceptionHandler(new MyExceptionHandler());
    }
}

class MyExceptionHandler implements Thread.UncaughtExceptionHandler
{
    @Override
    public void uncaughtException(Thread t, Throwable e) {
        RaygunClient client = new RaygunClient("YOUR_APP_API_KEY");
        client.Send(e);

    }
}

Or see the sample app which is where this code originates.

JSPs

The concept is the same for the above - set up an Unhandled Exception handler, then inside it create a RaygunClient and call Send() on it, passing in the exception. The way this is done will vary based on what framework you are using. Presented below is a naive example that just uses plain JSPs - this architecture is obviously not recommended. A similar method will work for raw servlets if happen to be using those.

Inside web.xml

<error-page>
  <exception-type>java.lang.Throwable</exception-type>
        <location>/error.jsp</location>
</error-page>

Inside error.jsp

<%@ page isErrorPage="true" %>
<%@ page import="com.mindscapehq.raygun4java.webprovider.RaygunServletClient" %>

<%
RaygunServletClient client = new RaygunServletClient("YOUR_APP_API_KEY", request);

client.Send(exception);
%>

When an exception is thrown from another JSP, this page will take care of the sending.

Note: all Java dynamic web page projects should have core-1.2..jar, webprovider-1.2..jar and gson-2.1.jar on their classpath.

Scala and Play 2 Framework

Download raygun4java-play2-1.x.x.jar from Maven or add the dependency to to your maven pom.xml.

For use in your Scala Play2 app's global error handler, RaygunPlayClient includes an overload which allows you to pass in a RequestHeader from Scala Play2:

override def onError(request: RequestHeader, ex: Throwable) = {
  val rg = new RaygunPlayClient("your_api_key", request)
  val result = rg.Send(ex)
  super.onError(request, ex)
}

Or, write code that sends an exception in your controller:

import play.api.mvc.{Action, Controller, Request}
import com.mindscapehq.raygun4java.play2.RaygunPlayClient;

def index = Action { implicit request =>
    val rg = new RaygunPlayClient("your_api_key", request)
    val result = rg.Send(new Exception("From Scala"))
    Ok(views.html.index(result.toString))
  }

Documentation

For complete documentation including asynchronous sending, user/version tracking and troubleshooting, view the Java documentation here.

Raygun4java GitHub Repository

For complete installation instructions, getting the source code and troubleshooting, visit the GitHub repository here.