djaceh@gmail.com | My favorites ▼ | Profile | Sign out soundcloudapi-java
Java wrapper for the SoundCloud API

Project Home
Downloads
Wiki
Issues
SourceSummary Updates People
Project Information
Star project
Activity Low
Project feeds
Code license
Apache License 2.0
Labels
soundcloud, java, api, audio, sound
Members
stjepan....@gmail.com
2 committers
Featured
Downloads
org.urbanstew.soundcloudapi-0.9.3.zip
Show all »
Links
External links
Code Documentation
SoundCloud API documentation
Groups
soundcloudapi Introduction

This is a Java wrapper for the SoundCloud API. The wrapper can be used to easily access the functionality of the API, including retrieving and manipulating resources such as user and track information, and uploading files.
Getting Started

To use the library, download the latest version and include the JAR files in your project. You can also access the library source from the repository.

The following library dependencies (and their dependencies) are included for convenience:
signpost, a light-weight client-side OAuth library
HttpClient 4.0, a robust HTTP client library


When using the library on Android, you may only need the following included JAR files:
apache-mime4j-0.6.jar
httpmime-4.0.jar
org.urbanstew.soundcloudapi-0.9.0.jar
signpost-commonshttp4-1.1.jar
signpost-core-1.1.jar

Otherwise, you may need all of the included JAR files.
Using the Code

The library interface is designed with simplicity in mind. Code samples below will illustrate a few basic use cases.
Authentication

SoundCloud uses the OAuth protocol to authenticate apps accessing protected data via the API. You will need to obtain a Consumer Key and Consumer Secret by registering your app with SoundCloud. A user can then allow your app to access protected data.

The SoundCloudAPI class is used to interface with the SoundCloud API. You can initialize an instance of this class as follows, if you intend to have the user allow access:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET);

To allow access, the user must visit an authentication URL (e.g., using a browser), and confirm that your app should be allowed access. SoundCloud will then issue a verification code, which needs to be delivered to your app. This can either be delivered manually by the user, or via a callback URL.
Step 1, Option 1: Manual Entry of Verification Code

If you need the user to manually provide your app with a verification code, do this:
String authorizationUrl = api.obtainRequestToken();

The user must then visit the authorizationUrl, obtain a verification code, and provide the code to your app.
Step 1, Option 2: Callback Delivery of the Verification Code

If your app can receive the verification code via a callback URL, do this:
String authorizationUrl = api.obtainRequestToken(YOUR_CALLBACK_URL);

In this case, after the user visits the authorizationUrl and allows access to the app, SoundCloud will redirect the user to your callback URL. The request will include an oauth_verifier value, which is the verification code.
Step 2: Obtaining the Access Token

Regardless of how your app obtains the verification code, proceed as follows:
api.obtainAccessToken(VERIFICATION_CODE);

You are now ready to start using the api object to send requests to the SoundCloud API.
Saving the Authentication for Later Use

Once you have obtained the authentication, you may want to save the Access Token and the Access Token Secret, so you don't have to authenticate your app / the user again:
String token = api.getToken();
String tokenSecret = api.getTokenSecret();

Next time you need to initialize a SoundCloudAPI object for the same user, simply provide the Access Token and the Access Token Secret:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, token, tokenSecret);

You are then ready to issue requests to the API.
Issuing Requests

Once the api object obtains the authentication information, it can be used to send requests to the SoundCloud API. This will return an org.apache.http.HttpResponse object, which you can use to process the response.
Example: Obtaining the User Information

The SoundCloud API provides the User resource for the authenticated user as the resource /me. This can be retrieved as follows:
HttpResponse response = api.get("me");
if(response.getStatusLine().getStatusCode() == 200)
{
DocumentBuilder db = DocumentBuilderFactory.newInstance().newDocumentBuilder();
Document dom = db.parse(response.getEntity().getContent());
// process the parsed XML via the dom object
// ...
}

The above code sample uses javax.xml.parsers.DocumentBuilder, javax.xml.parsers.DocumentBuilderFactory, and org.w3c.dom.Document to parse the response.
Example: Marking a Track as a Favorite

You can mark a track as a favorite of the authenticated user by issuing a put request:
HttpResponse response = api.put("me/favorites/" + TRACK_ID);
// process the response...
Example: Posting a Comment

The following example will post a comment for a track whose id is TRACK_ID:
List params = new java.util.ArrayList();
params.add(new BasicNameValuePair("comment[body]", "This is a test comment"));

HttpResponse response = api.post("tracks/" + TRACK_ID + "/comments", params);
// process the response, e.g. to get the id of the comment...
Example: Deleting a Comment

The following example will delete a comment with id COMMENT_ID:
HttpResponse response = api.delete("comments/" + COMMENT_ID);
// process the response...
Example: Uploading a File

The following example will upload a file via a POST request:
File file = new File(YOUR_FILE_NAME);

List params = new java.util.ArrayList();
params.add(new BasicNameValuePair("track[title]", "This is a test upload"));
params.add(new BasicNameValuePair("track[sharing]", "private"));

HttpResponse response = api.upload(file, params);
// process the response...
Playing in The Sandbox

SoundCloud provides a sandbox site which you can use to test your app's functionality. Note that you have to register your app separately for the sandbox site. To use the sandbox, you can provide an option when constructing the SoundCloudAPI object:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, SoundCloudAPI.USE_SANDBOX);

or
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, token, tokenSecret, SoundCloudAPI.USE_SANDBOX);
Further Reading
SoundCloud API documentation
SoundCloud Java wrapper Javadoc documentation

©2011 Google - Terms - Privacy - Project Hosting Help
Powered by Google Project Hosting

djaceh@gmail.com | My favorites ▼ | Profile | Sign out soundcloudapi-java
Java wrapper for the SoundCloud API

Project Home
Downloads
Wiki
Issues
SourceSummary Updates People
Project Information
Star project
Activity Low
Project feeds
Code license
Apache License 2.0
Labels
soundcloud, java, api, audio, sound
Members
stjepan....@gmail.com
2 committers
Featured
Downloads
org.urbanstew.soundcloudapi-0.9.3.zip
Show all »
Links
External links
Code Documentation
SoundCloud API documentation
Groups
soundcloudapi Introduction

This is a Java wrapper for the SoundCloud API. The wrapper can be used to easily access the functionality of the API, including retrieving and manipulating resources such as user and track information, and uploading files.
Getting Started

To use the library, download the latest version and include the JAR files in your project. You can also access the library source from the repository.

The following library dependencies (and their dependencies) are included for convenience:
signpost, a light-weight client-side OAuth library
HttpClient 4.0, a robust HTTP client library


When using the library on Android, you may only need the following included JAR files:
apache-mime4j-0.6.jar
httpmime-4.0.jar
org.urbanstew.soundcloudapi-0.9.0.jar
signpost-commonshttp4-1.1.jar
signpost-core-1.1.jar

Otherwise, you may need all of the included JAR files.
Using the Code

The library interface is designed with simplicity in mind. Code samples below will illustrate a few basic use cases.
Authentication

SoundCloud uses the OAuth protocol to authenticate apps accessing protected data via the API. You will need to obtain a Consumer Key and Consumer Secret by registering your app with SoundCloud. A user can then allow your app to access protected data.

The SoundCloudAPI class is used to interface with the SoundCloud API. You can initialize an instance of this class as follows, if you intend to have the user allow access:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET);

To allow access, the user must visit an authentication URL (e.g., using a browser), and confirm that your app should be allowed access. SoundCloud will then issue a verification code, which needs to be delivered to your app. This can either be delivered manually by the user, or via a callback URL.
Step 1, Option 1: Manual Entry of Verification Code

If you need the user to manually provide your app with a verification code, do this:
String authorizationUrl = api.obtainRequestToken();

The user must then visit the authorizationUrl, obtain a verification code, and provide the code to your app.
Step 1, Option 2: Callback Delivery of the Verification Code

If your app can receive the verification code via a callback URL, do this:
String authorizationUrl = api.obtainRequestToken(YOUR_CALLBACK_URL);

In this case, after the user visits the authorizationUrl and allows access to the app, SoundCloud will redirect the user to your callback URL. The request will include an oauth_verifier value, which is the verification code.
Step 2: Obtaining the Access Token

Regardless of how your app obtains the verification code, proceed as follows:
api.obtainAccessToken(VERIFICATION_CODE);

You are now ready to start using the api object to send requests to the SoundCloud API.
Saving the Authentication for Later Use

Once you have obtained the authentication, you may want to save the Access Token and the Access Token Secret, so you don't have to authenticate your app / the user again:
String token = api.getToken();
String tokenSecret = api.getTokenSecret();

Next time you need to initialize a SoundCloudAPI object for the same user, simply provide the Access Token and the Access Token Secret:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, token, tokenSecret);

You are then ready to issue requests to the API.
Issuing Requests

Once the api object obtains the authentication information, it can be used to send requests to the SoundCloud API. This will return an org.apache.http.HttpResponse object, which you can use to process the response.
Example: Obtaining the User Information

The SoundCloud API provides the User resource for the authenticated user as the resource /me. This can be retrieved as follows:
HttpResponse response = api.get("me");
if(response.getStatusLine().getStatusCode() == 200)
{
DocumentBuilder db = DocumentBuilderFactory.newInstance().newDocumentBuilder();
Document dom = db.parse(response.getEntity().getContent());
// process the parsed XML via the dom object
// ...
}

The above code sample uses javax.xml.parsers.DocumentBuilder, javax.xml.parsers.DocumentBuilderFactory, and org.w3c.dom.Document to parse the response.
Example: Marking a Track as a Favorite

You can mark a track as a favorite of the authenticated user by issuing a put request:
HttpResponse response = api.put("me/favorites/" + TRACK_ID);
// process the response...
Example: Posting a Comment

The following example will post a comment for a track whose id is TRACK_ID:
List params = new java.util.ArrayList();
params.add(new BasicNameValuePair("comment[body]", "This is a test comment"));

HttpResponse response = api.post("tracks/" + TRACK_ID + "/comments", params);
// process the response, e.g. to get the id of the comment...
Example: Deleting a Comment

The following example will delete a comment with id COMMENT_ID:
HttpResponse response = api.delete("comments/" + COMMENT_ID);
// process the response...
Example: Uploading a File

The following example will upload a file via a POST request:
File file = new File(YOUR_FILE_NAME);

List params = new java.util.ArrayList();
params.add(new BasicNameValuePair("track[title]", "This is a test upload"));
params.add(new BasicNameValuePair("track[sharing]", "private"));

HttpResponse response = api.upload(file, params);
// process the response...
Playing in The Sandbox

SoundCloud provides a sandbox site which you can use to test your app's functionality. Note that you have to register your app separately for the sandbox site. To use the sandbox, you can provide an option when constructing the SoundCloudAPI object:
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, SoundCloudAPI.USE_SANDBOX);

or
SoundCloudAPI api = new SoundCloudAPI(YOUR_APP_CONSUMER_KEY, YOUR_APP_CONSUMER_SECRET, token, tokenSecret, SoundCloudAPI.USE_SANDBOX);
Further Reading
SoundCloud API documentation
SoundCloud Java wrapper Javadoc documentation

©2011 Google - Terms - Privacy - Project Hosting Help
Powered by Google Project Hosting

Last Published: 2011-03-19 | Version: 4.1.1
Apache | HttpComponents
HttpComponents
Home
License
Download
Mailing Lists
User documents
Developer documents
Wiki (external)
Security
HttpClient Overview
Description
Quick Start
Documentation
Tutorial
Examples
Client HTTP Programming Primer
Logging
Modules
HttpClient
HttpMime
HttpClient Cache
Project Documentation
Project Information
ASF
ASF Home Page
Foundation
Sponsor Apache
Thanks

HttpClient Overview

The Hyper-Text Transfer Protocol (HTTP) is perhaps the most significant protocol used on the Internet today. Web services, network-enabled appliances and the growth of network computing continue to expand the role of the HTTP protocol beyond user-driven web browsers, while increasing the number of applications that require HTTP support.

Although the java.net package provides basic functionality for accessing resources via HTTP, it doesn't provide the full flexibility or functionality needed by many applications. HttpClient seeks to fill this void by providing an efficient, up-to-date, and feature-rich package implementing the client side of the most recent HTTP standards and recommendations.

Designed for extension while providing robust support for the base HTTP protocol, HttpClient may be of interest to anyone building HTTP-aware client applications such as web browsers, web service clients, or systems that leverage or extend the HTTP protocol for distributed communication.
Documentation
HttpClient Tutorial ( HTML / PDF )
Some examples of HttpClient in action can be found here
Features
Standards based, pure Java, implementation of HTTP versions 1.0 and 1.1
Full implementation of all HTTP methods (GET, POST, PUT, DELETE, HEAD, OPTIONS, and TRACE) in an extensible OO framework.
Supports encryption with HTTPS (HTTP over SSL) protocol.
Transparent connections through HTTP proxies.
Tunneled HTTPS connections through HTTP proxies, via the CONNECT method.
Basic, Digest, NTLMv1, NTLMv2, NTLM2 Session, SNPNEGO/Kerberos authentication schemes.
Plug-in mechanism for custom authentication schemes.
Pluggable secure socket factories, making it easier to use third party solutions
Connection management support for use in multi-threaded applications. Supports setting the maximum total connections as well as the maximum connections per host. Detects and closes stale connections.
Automatic Cookie handling for reading Set-Cookie: headers from the server and sending them back out in a Cookie: header when appropriate.
Plug-in mechanism for custom cookie policies.
Request output streams to avoid buffering any content body by streaming directly to the socket to the server.
Response input streams to efficiently read the response body by streaming directly from the socket to the server.
Persistent connections using KeepAlive in HTTP/1.0 and persistance in HTTP/1.1
Direct access to the response code and headers sent by the server.
The ability to set connection timeouts.
Experimental support for HTTP/1.1 response caching.
Source code is freely available under the Apache License.
Standards Compliance

HttpClient strives to conform to the following specifications endorsed by the Internet Engineering Task Force (IETF) and the internet at large:
RFC 1945 Hypertext Transfer Protocol -- HTTP/1.0
RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
RFC 2617 HTTP Authentication: Basic and Digest Access Authentication
RFC 2109 HTTP State Management Mechanism (Cookies)
RFC 2965 HTTP State Management Mechanism (Cookies v2)
Apache HttpComponents, Commons HttpClient, Apache, the Apache feather logo, and the Apache HttpComponents project logo are trademarks of The Apache Software Foundation.

All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Copyright © 1999-2011 The Apache Software Foundation. All Rights Reserved.

Last Published: 2011-03-19 | Version: 4.1.1
Apache | HttpComponents
HttpComponents
Home
License
Download
Mailing Lists
User documents
Developer documents
Wiki (external)
Security
HttpClient Overview
Description
Quick Start
Documentation
Tutorial
Examples
Client HTTP Programming Primer
Logging
Modules
HttpClient
HttpMime
HttpClient Cache
Project Documentation
Project Information
ASF
ASF Home Page
Foundation
Sponsor Apache
Thanks

Logging Practices

Being a library HttpClient is not to dictate which logging framework the user has to use. Therefore HttpClient utilizes the logging interface provided by the Commons Logging package. Commons Logging provides a simple and generalized log interface to various logging packages. By using Commons Logging, HttpClient can be configured for a variety of different logging behaviours. That means the user will have to make a choice which logging framework to use. By default Commons Logging supports the following logging frameworks:
Log4J
java.util.logging
SimpleLog (internal to Commons Logging)

By implementing some simple interfaces Commons Logging can be extended to support basically any other custom logging framework. Commons Logging tries to automatically discover the logging framework to use. If it fails to select the expected one, you must configure Commons Logging by hand. Please refer to the Commons Logging documentation for more information.

HttpClient performs three different kinds of logging: the standard context logging used within each class, HTTP header logging and full wire logging.
Context Logging

Context logging contains information about the internal operation of HttpClient as it performs HTTP requests. Each class has its own log named according to the class's fully qualified name. For example the class DefaultHttpClient has a log named org.apache.http.impl.client.DefaultHttpClient. Since all classes follow this convention it is possible to configure context logging for all classes using the single log named org.apache.http.impl.client.
Wire Logging

The wire log is used to log all data transmitted to and from servers when executing HTTP requests. The wire log uses the org.apache.http.wire logging category. This log should only be enabled to debug problems, as it will produce an extremely large amount of log data.
HTTP header Logging

Because the content of HTTP requests is usually less important for debugging than the HTTP headers, the org.apache.http.headers logging category for capturing HTTP headers only.
Configuration Examples

Commons Logging can delegate to a variety of loggers for processing the actual output. Below are configuration examples for Commons Logging, Log4j and java.util.logging.
Commons Logging Examples

Commons Logging comes with a basic logger called SimpleLog. This logger writes all logged messages to System.err. The following examples show how to configure Commons Logging via system properties to use SimpleLog. It is strongly recommended to configure Commons Logging system properties through JVM process arguments at the start up.
Enable header wire + context logging - Best for Debugging
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR
Enable full wire + context logging
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
Enable context logging for connection management
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
Enable context logging for connection management / request execution
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.client=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.client=DEBUG
Log4j Examples

The simplest way to configure Log4j is via a log4j.properties file. Log4j will automatically read and configure itself using a file named log4j.properties when it's present at the root of the application classpath. Below are some Log4j configuration examples.

Note: Log4j is not included in the HttpClient distribution.
Enable header wire + context logging - Best for Debugging
log4j.rootLogger=INFO, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n

log4j.logger.org.apache.http=DEBUG
log4j.logger.org.apache.http.wire=ERROR
Enable full wire + context logging
log4j.rootLogger=INFO, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n

log4j.logger.org.apache.http=DEBUG
Enable context logging for connection management
log4j.rootLogger=INFO, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n

log4j.logger.org.apache.http.impl.conn=DEBUG
Enable context logging for connection management / request execution
log4j.rootLogger=INFO, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n

log4j.logger.org.apache.http.impl.conn=DEBUG
log4j.logger.org.apache.http.impl.client=DEBUG
log4j.logger.org.apache.http.client=DEBUG

Note that the default configuration for Log4J is very inefficient as it causes all the logging information to be generated but not actually sent anywhere. The Log4J manual is the best reference for how to configure Log4J. It is available at http://logging.apache.org/log4j/docs/manual.html.
java.util.logging Examples

Since JDK 1.4 there has been a package java.util.logging that provides a logging framework similar to Log4J. By default it reads a config file from $JAVA_HOME/jre/lib/logging.properties which looks like this (comments stripped):
handlers=java.util.logging.ConsoleHandler
.level=INFO
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
com.xyz.foo.level = SEVERE

To customize logging a custom logging.properties file should be created in the project directory. The location of this file must be passed to the JVM as asystem property. This can be done on the command line like so:
$JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties
-classpath $HOME/myapp/target/classes com.myapp.Main

Alternatively LogManager#readConfiguration(InputStream) can be used to pass it the desired configuration.
Enable header wire + context logging - Best for Debugging
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.level = FINEST
org.apache.http.wire.level = SEVERE
Enable full wire + context logging
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.level = FINEST
Enable context logging for connection management
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.impl.conn.level = FINEST
Enable context logging for connection management / request execution
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.impl.conn.level = FINEST
org.apache.http.impl.client.level = FINEST
org.apache.http.client.level = FINEST

More detailed information is available from the Java Logging documentation.
Apache HttpComponents, Commons HttpClient, Apache, the Apache feather logo, and the Apache HttpComponents project logo are trademarks of The Apache Software Foundation.

All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Copyright © 1999-2011 The Apache Software Foundation. All Rights Reserved.

Overview Package Class Use Tree Deprecated Index Help
JavaTM 2 Platform
Std. Ed. v1.4.2
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

Package java.util.logging
Provides the classes and interfaces of the JavaTM 2 platform's core logging facilities.

See:
Description
Interface Summary
Filter A Filter can be used to provide fine grain control over what is logged, beyond the control provided by log levels.


Class Summary
ConsoleHandler This Handler publishes log records to System.err.
ErrorManager ErrorManager objects can be attached to Handlers to process any error that occur on a Handler during Logging.
FileHandler Simple file logging Handler.
Formatter A Formatter provides support for formatting LogRecords.
Handler A Handler object takes log messages from a Logger and exports them.
Level The Level class defines a set of standard logging levels that can be used to control logging output.
Logger A Logger object is used to log messages for a specific system or application component.
LoggingPermission The permission which the SecurityManager will check when code that is running with a SecurityManager calls one of the logging control methods (such as Logger.setLevel).
LogManager There is a single global LogManager object that is used to maintain a set of shared state about Loggers and log services.
LogRecord LogRecord objects are used to pass logging requests between the logging framework and individual log Handlers.
MemoryHandler Handler that buffers requests in a circular buffer in memory.
SimpleFormatter Print a brief summary of the LogRecord in a human readable format.
SocketHandler Simple network logging Handler.
StreamHandler Stream based logging Handler.
XMLFormatter Format a LogRecord into a standard XML format.



Package java.util.logging Description


Provides the classes and interfaces of the JavaTM 2 platform's core logging facilities. The central goal of the logging APIs is to support maintaining and servicing software at customer sites.

There are four main target uses of the logs:
Problem diagnosis by end users and system administrators. This consists of simple logging of common problems that can be fixed or tracked locally, such as running out of resources, security failures, and simple configuration errors.
Problem diagnosis by field service engineers. The logging information used by field service engineers may be considerably more complex and verbose than that required by system administrators. Typically such information will require extra logging within particular subsystems.
Problem diagnosis by the development organization. When a problem occurs in the field, it may be necessary to return the captured logging information to the original development team for diagnosis. This logging information may be extremely detailed and fairly inscrutable. Such information might include detailed tracing on the internal execution of particular subsystems.
Problem diagnosis by developers. The Logging APIs may also be used to help debug an application under development. This may include logging information generated by the target application as well as logging information generated by lower-level libraries. Note however that while this use is perfectly reasonable, the logging APIs are not intended to replace the normal debugging and profiling tools that may already exist in the development environment.

The key elements of this package include:
Logger: The main entity on which applications make logging calls. A Logger object is used to log messages for a specific system or application component.
LogRecord: Used to pass logging requests between the logging framework and individual log handlers.
Handler: Exports LogRecord objects to a variety of destinations including memory, output streams, consoles, files, and sockets. A variety of Handler subclasses exist for this purpose. Additional Handlers may be developed by third parties and delivered on top of the core platform.
Level: Defines a set of standard logging levels that can be used to control logging output. Programs can be configured to output logging for some levels while ignoring output for others.
Filter: Provides fine-grained control over what gets logged, beyond the control provided by log levels. The logging APIs support a general-purpose filter mechanism that allows application code to attach arbitrary filters to control logging output.
Formatter: Provides support for formatting LogRecord objects. This package includes two formatters, SimpleFormatter and XMLFormatter, for formatting log records in plain text or XML respectively. As with Handlers, additional Formatters may be developed by third parties.

The Logging APIs offer both static and dynamic configuration control. Static control enables field service staff to set up a particular configuration and then re-launch the application with the new logging settings. Dynamic control allows for updates to the logging configuration within a currently running program. The APIs also allow for logging to be enabled or disabled for different functional areas of the system. For example, a field service engineer might be interested in tracing all AWT events, but might have no interest in socket events or memory management.
Null Pointers

In general, unless otherwise noted in the javadoc, methods and contructors will throw NullPointerException if passed a null argument. The one broad exception to this rule is that the logging convenience methods in the Logger class (the config, entering, exiting, fine, finer, finest, log, logp, logrb, severe, throwing, and warning methods) will accept null values for all arguments except for the initial Level argument (if any).

Related Documentation

For an overview of control flow, please refer to the Java Logging Overview.


Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
JavaTM 2 Platform
Std. Ed. v1.4.2
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES All Classes

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 2003, 2010 Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.