Getting Started

System Requirements

Admin4J 1.0.4 and later requires the following software to run:

  • Java JDK V1.6 or later
  • Slf4J 1.6 or later.
  • Freemarker 2.0 or later.

Admin4J up through V1.0.3 requires the following software to run:

  • Java JDK V1.5 or later
  • Slf4J 1.5 or later.
  • Freemarker 2.0 or later.

Admin4J can be configured via Maven

<dependency>
  <groupId>net.admin4j</groupId>
  <artifactId>admin4j</artifactId>
  <version>${admin4j.version}</version>
</dependency>

Sample Web Application

Admin4J comes with a sample application preconfigured with all of these utilities.

Configuring Admin4J

Configuration of Admin4J occurs in two places:

  • admin4j.properties file
  • web.xml

Specifying configuration properties

Configuration properties can be specified in two ways:

  • By setting system property 'admin4j.configuration.file' equal to a properties file name containing the admin4j configuration.
  • Placing a file called 'admin4j.properties' in the classpath.

If both the system property is specified and an admin4j.properties file is placed in the classpath, the system property takes precedence.

Note that all property values can refer to system property settings using the syntax ${variable-name}. For example, if you set the exception info file location to '${user.dir}/admin4j.sample.webapp.exceptionInfo.xml', the value of '${user.dir} will evaluate to the user.dir System property.

An abbreviated list of configuration properties needed by most users is listed below. A complete reference for available configuration properties can be found here

Property Required Options Default Description
exception.info.storage.format N xml Specifies the format used to store tracked exceptions and exception statistics.
exception.info.xml.file N null Specifies a fully-qualified or relative file location for exception tracking information.
performance.info.storage.format N xml Specifies the format used to store performance metric information.
performance.info.xml.file N null Specifies a fully-qualified or relative file location for performance metric information.
default.notifier.class N Any class implementing net.admin4j.util.notify.Notifier null Specifies the default notifier used for all admin4j notifications. You can always override the default for Admin4J servlets and filters in the file web.xml.

All Admin4J Email Notifiers support the following properties:

Property Required Description
default.notifier.mail.server.host Y if default.notifier.class specifies an Admin4J Email Notifier Specifies the hostname for your email server.
default.notifier.from.email.address Y if default.notifier.class specifies an Admin4J Email Notifier Specifies the email address from which all notifications will be received.
default.notifier.to.email.address Y if default.notifier.class specifies an Admin4J Email Notifier Specifies the email address to which all notifications will be received.

Sample admin4j.properties file:

######################################################333
#
#	admin4j.properties sample
#

exception.info.storage.format=xml
exception.info.xml.file=${user.dir}/admin4j.sample.webapp.exceptionInfo.xml
performance.info.storage.format=xml
performance.info.xml.file=${user.dir}/admin4j.sample.webapp.performanceInfo.xml

default.notifier.class=net.admin4j.util.notify.HtmlEmailNotifier
default.notifier.mail.server.host=localhost
default.notifier.from.email.address=test@admin4j.net
default.notifier.to.email.address=test@localhost

web.xml changes

Filter definition and mapping

Define the following Servlet Filter and filter mapping.

<filter>
	<filter-name>Admin4J Standard Filter</filter-name>
	<filter-class>
		net.admin4j.ui.filters.Admin4JStandardFilter
	</filter-class>
</filter>

<filter-mapping>
	<filter-name>Admin4J Standard Filter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

Servlet definition and mapping

Define the following Servlet and servlet mappings.

<servlet>
	<servlet-name>Admin4J Index Servlet</servlet-name>
	<servlet-class>net.admin4j.ui.servlets.Admin4JHomePageServlet</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
	<servlet-name>Admin4J Index Servlet</servlet-name>
	<url-pattern>/admin4j/index</url-pattern>
</servlet-mapping>
<servlet-mapping>
	<servlet-name>Admin4J Index Servlet</servlet-name>
	<url-pattern>/admin4j/index/*</url-pattern>
</servlet-mapping>

How to use Admin4J

The following items were installed if you followed the instructions above:

Feature Description
The Admin4J Home Page Contains a link to all other Admin4J pages installed by default.
Exception Summary page and Error Notification features Display the Exception Summary page and get notifications for web application errors as described in the Exception Management section.
Thread contention monitoring and notification features Receive thread contention alerts as described in the Thread Contention section.
Memory monitor and low availability notification features Receive low memory availability alerts as described in the Memory issues section.
Performance Tracking features track performance for all web application pages and display performance statistics as described in the Performance Tracking section.
HotSpot Identify where the "hot spots" in our applications are as described in the HotSpot section.
Logger management features Manipulate log level settings at runtime as described in the Logger Management section.
File Explorer features Browse you containers underlyinf file system as described in the File Explorer section.
JMX Browsing features Obtain all published JMX information even if you haven't exposed a JMX port for remote consoles as described in the JMX Explorer section.

If you installed the home page servlet mappings as described above, you can surf to the admin4j home page, which looks like the following:

Admin4J Home Page