org.apache.cocoon.util.location
Class LocationUtils

java.lang.Object
  extended byorg.apache.cocoon.util.location.LocationUtils

public class LocationUtils
extends Object

Location-related utility methods.

Since:
2.1.8
Version:
$Id: LocationUtils.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Nested Class Summary
static interface LocationUtils.LocationFinder
          An finder or object locations
 
Field Summary
static String UNKNOWN_STRING
          The string representation of an unknown location: "[unknown location]".
 
Method Summary
static void addFinder(LocationUtils.LocationFinder finder)
          Add a LocationUtils.LocationFinder to the list of finders that will be queried for an object's location by getLocation(Object, String).
static Location getLocation(Object obj)
          Get the location of an object.
static Location getLocation(Object obj, String description)
          Get the location of an object.
static boolean isKnown(Location location)
          Checks if a location is known, i.e.
static boolean isUnknown(Location location)
          Checks if a location is unknown, i.e.
static LocationImpl parse(String text)
          Parse a location string of the form "uri:line:column" (e.g.
static String toString(Location location)
          Builds a string representation of a location, in the "descripton - uri:line:column" format (e.g.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_STRING

public static final String UNKNOWN_STRING
The string representation of an unknown location: "[unknown location]".

See Also:
Constant Field Values
Method Detail

toString

public static String toString(Location location)
Builds a string representation of a location, in the "descripton - uri:line:column" format (e.g. "foo - file://path/to/file.xml:3:40"). For an unknown location, returns UNKNOWN_STRING.

Returns:
the string representation

parse

public static LocationImpl parse(String text)
                          throws IllegalArgumentException
Parse a location string of the form "uri:line:column" (e.g. "path/to/file.xml:3:40") to a Location object. Additionally, a description may also optionally be present, separated with an hyphen (e.g. "foo - path/to/file.xml:3.40").

Parameters:
text - the text to parse
Returns:
the location (possibly null if text was null or in an incorrect format)
Throws:
IllegalArgumentException

isKnown

public static boolean isKnown(Location location)
Checks if a location is known, i.e. it is not null nor equal to Location.UNKNOWN.

Parameters:
location - the location to check
Returns:
true if the location is known

isUnknown

public static boolean isUnknown(Location location)
Checks if a location is unknown, i.e. it is either null or equal to Location.UNKNOWN.

Parameters:
location - the location to check
Returns:
true if the location is unknown

addFinder

public static void addFinder(LocationUtils.LocationFinder finder)
Add a LocationUtils.LocationFinder to the list of finders that will be queried for an object's location by getLocation(Object, String).

Important: LocationUtils internally stores a weak reference to the finder. This avoids creating strong links between the classloader holding this class and the finder's classloader, which can cause some weird memory leaks if the finder's classloader is to be reloaded. Therefore, you have to keep a strong reference to the finder in the calling code, e.g.:

   private static LocationUtils.LocationFinder myFinder =
       new LocationUtils.LocationFinder() {
           public Location getLocation(Object obj, String desc) {
               ...
           }
       };

   static {
       LocationUtils.addFinder(myFinder);
   }
 

Parameters:
finder - the location finder to add

getLocation

public static Location getLocation(Object obj)
Get the location of an object. Some well-known located classes built in the JDK are handled by this method. Handling of other located classes can be handled by adding new location finders.

Parameters:
obj - the object of which to get the location
Returns:
the object's location, or Location.UNKNOWN if no location could be found

getLocation

public static Location getLocation(Object obj,
                                   String description)
Get the location of an object. Some well-known located classes built in the JDK are handled by this method. Handling of other located classes can be handled by adding new location finders.

Parameters:
obj - the object of which to get the location
description - an optional description of the object's location, used if a Location object has to be created.
Returns:
the object's location, or Location.UNKNOWN if no location could be found


Copyright © 1999-2008 The Apache Software Foundation. All Rights Reserved.