A Simple Logging Sample Application

> A Simple Logging Sample Application
> This sample application document contains the following sections:

> Overview

> - Compiling and Assembling the Application

> - Deploying the Sample Application

> - Running the Sample Application

> - Troubleshooting

> Overview

> The essence of this sample is to demonstrate the use of Loggers in writing enterprise applications. A Logger object is used to log messages for a specific system or application component. Log messages help developers debug their applications.

> JavaTM 2 Platform Std. Ed. v1.4.0 introduces a new package java.util.logging, that has all the classes and interfaces for the core logging facilities. The central goal of the logging APIs is to support maintaining and servicing software at customer sites.

> Typically, the application developer uses a Logger object with a name that corresponds to the class or package name of the application to generate log messages -- at any of seven severity levels (defined by the Level class).

> These messages might report errors and warnings, or provide informational messages about interesting events in the application's lifecycle. They can include debugging information, or even trace the execution of important methods within the program. It is not intended that all of these messages will actually be generated and logged all of the time; there is a default logging configuration file that specifies where log messages are directed to (the console, a file, a network socket, or a combination of these), how they are formatted (as plain text or XML documents), and at what severity threshold they are logged (log messages with a severity below the specified threshold are discarded with very little overhead and should not significantly impact the performance of the application.) The system administrator or end user of the application can modify this default configuration to suit their needs.

> The java.util.logging package is very flexible, and can be used in a number of ways. For most applications, however, use of the Logging API is quite simple. Obtain a named Logger object whenever necessary by calling the static Logger.getLogger() method, passing the class or package name of the application as the logger name. Then use one of the many Logger instance methods to generate log messages. The easiest methods to use have names that correspond to severity levels, such as severe(), warning(), info(), and debug()

> We will demonstrate the use of these loggers in our sample in four different ways:

> - Print log messages with System.err.println (Not using loggers)
> - Print INFO log using java.util.logging.Logger
> - Bypass log-level and log using a lower log-level
> - Log to a file (Can be set in log.properties. Default is helloworld.log)
> The sample code comes ready with a wide range of logging APIs. Based on user's selection, the application starts logging messages to the server.log file. However, the later two selections need some special treatment. See Running the Sample, section for details.

> Following section will guide you through the execution of the sample.

> Bring up a web page with a form like the one seen in Figure 1.

> Figure 1 Logging front page

> Enter your name, make your logging selection and press the Process button.

> 2. A servlet gets invoked and in turn calls a stateless session bean to determine a greeting based upon the current system time.

> 3. Both the servlet and the bean start writing log messages, based on user's logging selection.

> 4. The servlet dispatches a JSP to deliver the greeting back to the browser.

> 5. As a result of the JSP execution, you can see the page displayed in Figure 2 returned to your browser.

> Figure 2 Logging results page

> Compiling and Assembling the Application

> In this section, a procedure describes how to assemble and compile the sample using a Command Line Interface (CLI).

> To rebuild the entire application from scratch, follow these steps:

> Compile and Assemble Logging Sample. For example:

> Execute asant under <s1as_install_dir>/samples/logging/simple/src/.

> The default target core will be executed to rebuild the WAR and EAR files.

> Deploy the application.

> Once you have re-created the sample application from scratch, you may proceed to Deploying the Sample Application.

> Clean the web application project area. For example:

> Execute asant clean to remove the sample application's assemble and build directories.

> You are now ready to use this EAR file for deployment.

> Deploying the Sample Application

> You may select one of the following methods of deploying and registering the application:

> Command Line Interface (CLI)-based Deployment describes how to manually register the sample application using a Command Line Interface (CLI). This is the fastest means of deploying the application to the application server.

> - Web Interface (GUI)-based Deployment describes how to use the Sun ONE Deployment Tool to import and deploy the sample application.

> Command Line Interface (CLI)-based Deployment
> Since the sample application is supplied with a complete EAR file, the fastest means of setting up the application is to use the command line utilities as described in this section. If you would like to experience either deploying through a Web based tool, then follow instructions in Web Interface (GUI)-based Deployment.

> The pre-built logging-helloworld.ear file is a Enterprise Archive file that contains the Web Archive (WAR) file of the application. Within the WAR file resides the XML deployment descriptor files, application class files, JSPs and other content required by the application.

> Deploying the pre-built logging-helloworld.ear file is simple. Deploy either using a Using asant script or Using asadmin command.

> Using asant script

> Go to the src directory of the sample. For example:

> <s1as_install_dir>/samples/logging/simple/src

> Execute the following command:

> asant deploy

> Using asadmin command

> Go to the root of the sample directory. For example:

> <s1as_install_dir>/samples/logging/simple/

> Execute asadmin to deploy the module to the local application server instance. For example:

> asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> logging-helloworld.ear

> The deployment process involves the following operations:

> Authenticates against the local application server's administrative server.

> - The EAR file is transferred to the administrative server.

> - The administrative server begins the registration process:

>   Parses the EAR file and embedded WAR file

>   - Explodes the bits into repository

>   - Registers the J2EE application logging-helloworld by updating server.xml.

> If you would like to verify the registration of the application, proceed to Verifying Registration. Otherwise, you are now ready to exercise the application by Running the Sample Application.

> Verifying Registration
> As an optional step, you can use the Sun ONE Application Server Administration Tool to verify that the application has been registered. If you do not want to verify that the application has been registered, proceed directly to Running the Sample Application.

> To verify the registration of the application, do one of the following:

> Execute asadmin to look at applications deployed with a server instance. For example:

> asadmin list-components -u <username> -w <password> -H <host> -p <admin-port> <server instance name>

> You will see the logging-helloworld app as one of the listed applications.

> OR

> Navigate the Admin tool GUI to

> App Server Instances>server1>Applications>Enterprise Apps.

> Click on Enterprise Apps on the left frame menu to diplay list of applications deployed on server.

> Web Interface (GUI)-based Deployment
> Since a pre-built Enterprise Archive (EAR) file for the sample application is included with the application server, you can use the Sun ONE Application Server Administration Tool to quickly read in the .ear file and deploy it to the application server.

> Open the pre-existing sample EAR file.

> 2. Start the admin server if not already started using one of the following two methods, depending on your Operations System:

>    UNIX

>    Execute <install_dir>/domains/domain1/admin-server/bin/startserv

>    Windows

>    Start->Programs->Sun ONE Application Server 7->Start Application Server

>    - Open the EAR file.

>    Navigate to the browser based admin server page [http://<server-host>:<admin-port>/index.html]. Enter your username and password to access the admin server.

>    - Click on App Server Instances>server1>Applications>Enterprise Apps.

>    - In the right hand pane, click on Deploy to deploy an application. Choose the file (from disk) to be deployed (logging-helloworld.ear) and Click OK.

>    - You will be asked for the application name. Enter logging-helloworld and Click OK.

>    If the deployment goes through fine, you will see the original pane with logging-helloworld application as deployed.

> Running the Sample Application

> Unlike any other sample, running this sample is not as simple as typing-in the url http://<hostname>:<port>/logging-helloworld. There is more to it.

> As we discussed earlier in the overview section, we have four options to choose from. They are:

> - Print log messages with System.err.println (Not using loggers)
> - Print INFO log using java.util.logging.Logger
> - Bypass log-level and log using a lower log-level
> - Log to a file (Can be set in log.properties. Default is helloworld.log)

> Note
> Running these options requires special access control permission, since they try to overwrite the default logging mechanism of the server. This requires a change in the server.policy file. This file can be found at <s1as-instance-dir>/domains/domain1/server1/config.

> Add the following entries to your server.policy file:

> grant codeBase "file:${com.sun.aas.instanceRoot}/domains/domain1/server1/applications/j2ee-apps/logging-helloworld_1/logging-helloworld_war/WEB-INF/classes/-" { permission java.util.logging.LoggingPermission "control"; };
> grant codeBase "file:${com.sun.aas.instanceRoot}/domains/domain1/server1/applications/j2ee-apps/logging-helloworld_1/logging-helloworldEjb_jar/-" { permission java.util.logging.LoggingPermission "control"; };

> For the last option, a log file of our choice can be specified in log.properties file, that comes bundled with this sample. The content looks as follows:

> # Log File
> log_file=../logs/helloworld.log

> # Log Level (One of, SEVERE,WARNING,INFO,CONFIG,FINE,FINER and FINEST)
> log_level=FINE

> Please restart server instance. Now we are ready to run the application. Log messages will be generated in server.log file. For the fourth option, log will also be generated in the specified log file in log.properties.

> Output (Option 1)
> [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: GreeterServlet is executing ... [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Looking up greeter bean home interface using JNDI name: java:comp/env/ejb/logger [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Bean found!!! [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Creating a remote bean object... [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Calling bean's getGreeting method... [14/Aug/2002:00:40:25] INFO (13546): inside the getGreeting method of the bean... [14/Aug/2002:00:40:25] INFO (13546): returnig message to the caller... [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Got message from greeter bean: morning [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Storing the message in request object [14/Aug/2002:00:40:25] WARNING (13546): CORE3283: stderr: Dispatching JSP for output

> Output (Option 2)
> [14/Aug/2002:00:54:12] INFO (13546): GreeterServlet is executing ... [14/Aug/2002:00:54:12] INFO (13546): Looking up greeter bean home interface using JNDI name: java:comp/env/ejb/logger [14/Aug/2002:00:54:12] INFO (13546): Bean found!!! [14/Aug/2002:00:54:12] INFO (13546): Creating a remote bean object... [14/Aug/2002:00:54:12] INFO (13546): Calling bean's getGreeting method... [14/Aug/2002:00:54:12] INFO (13546): inside the getGreeting method of the bean... [14/Aug/2002:00:54:12] INFO (13546): returnig message to the caller... [14/Aug/2002:00:54:12] INFO (13546): Got message from greeter bean: morning [14/Aug/2002:00:54:12] INFO (13546): Storing the message in request object [14/Aug/2002:00:54:12] INFO (13546): Dispatching JSP for output

> Output (Option 3)
> [14/Aug/2002:00:56:28] WARNING (13546): Trying to set the log level to FINE [14/Aug/2002:00:56:28] FINE (13546): Changed the log level to FINE. [14/Aug/2002:00:56:28] FINE (13546): GreeterServlet is executing ... [14/Aug/2002:00:56:28] FINE (13546): Looking up greeter bean home interface using JNDI name: java:comp/env/ejb/logger [14/Aug/2002:00:56:28] FINE (13546): Bean found!!! [14/Aug/2002:00:56:28] FINE (13546): Creating a remote bean object... [14/Aug/2002:00:56:28] FINE (13546): Calling bean's getGreeting method... [14/Aug/2002:00:56:28] INFO (13546): inside the getGreeting method of the bean... [14/Aug/2002:00:56:28] INFO (13546): returnig message to the caller... [14/Aug/2002:00:56:28] FINE (13546): Got message from greeter bean: morning [14/Aug/2002:00:56:28] FINE (13546): Storing the message in request object [14/Aug/2002:00:56:28] FINE (13546): Dispatching JSP for output

> Output (Option 4)
> [14/Aug/2002:00:57:06] INFO (13546): GreeterServlet is executing ... [14/Aug/2002:00:57:06] INFO (13546): Looking up greeter bean home interface using JNDI name: java:comp/env/ejb/logger [14/Aug/2002:00:57:06] INFO (13546): Bean found!!! [14/Aug/2002:00:57:06] INFO (13546): Creating a remote bean object... [14/Aug/2002:00:57:06] INFO (13546): Calling bean's getGreeting method... [14/Aug/2002:00:57:06] INFO (13546): inside the getGreeting method of the bean... [14/Aug/2002:00:57:06] INFO (13546): returnig message to the caller... [14/Aug/2002:00:57:06] INFO (13546): Got message from greeter bean: morning [14/Aug/2002:00:57:06] INFO (13546): Storing the message in request object [14/Aug/2002:00:57:06] INFO (13546): Dispatching JSP for output [

> Similar log messages will be generated, in the log file specified in log.properties file.

> Troubleshooting

> Although the war, ear, context-root and servlet alias names in this sample are all logging-helloworld, it is not necessary that it be so. The application will work as expected if the names of each of these attributes is unique. Rebuild the app after changing the context-root (in application.xml), the servlet alias (in web.xml) and the war and ear names, redeploy and test the sample to confirm this.

> - If you encounter problems when running the application, review the log files at <s1as-instance-dir>/domains/domain1/<server-instance>/logs/server.log to learn what exactly went wrong.

> Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated August 13, 2002