com.android.tools.lint.detector.api
Class Location

java.lang.Object
  com.android.tools.lint.detector.api.Location

@Beta
public class Location
extends java.lang.Object

Location information for a warning

NOTE: This is not a public or final API; if you rely on this be prepared to adjust your code for the next tools release.

Nested Class Summary

static class	Location.DefaultLocationHandle A default Location.Handle implementation for simple file offsets
static interface	Location.Handle A Location.Handle is a reference to a location.
static class	Location.ResourceItemHandle
static class	Location.SearchDirection Whether to look forwards, or backwards, or in both directions, when searching for a pattern in the source code to determine the right position range for a given symbol.
static class	Location.SearchHints Extra information pertaining to finding a symbol in a source buffer, used by create(File, String, int, String, String, SearchHints)

Constructor Summary

protected

Location(java.io.File file, Position start, Position end) (Private constructor, use one of the factory methods create(File), create(File, Position, Position), or create(File, String, int, int).

Method Summary

static Location	create(java.io.File file) Creates a new location for the given file
static Location	create(java.io.File file, Position start, Position end) Creates a new location for the given file and starting and ending positions.
static Location	create(java.io.File file, java.lang.String contents, int line) Creates a new location for the given file, with the given contents, for the given line number.
static Location	create(java.io.File file, java.lang.String contents, int startOffset, int endOffset) Creates a new location for the given file, with the given contents, for the given offset range.
static Location	create(java.io.File file, java.lang.String contents, int line, java.lang.String patternStart, java.lang.String patternEnd, Location.SearchHints hints) Creates a new location for the given file, with the given contents, for the given line number.
java.lang.Object	getClientData() Returns the client data associated with this location - an optional field which can be used by the creator of the Location to store temporary state associated with the location.
Position	getEnd() The end position of the range
java.io.File	getFile() Returns the file containing the warning.
java.lang.String	getMessage() Returns the custom message for this location, if any.
Location	getSecondary() Returns a secondary location associated with this location (if applicable), or null.
Position	getStart() The start position of the range
static Location	reverse(Location location) Reverses the secondary location list initiated by the given location
void	setClientData(java.lang.Object clientData) Sets the client data associated with this location.
void	setMessage(java.lang.String message) Sets a custom message for this location.
void	setSecondary(Location secondary) Sets a secondary location for this location.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Location

protected Location(@NonNull
                   java.io.File file,
                   @Nullable
                   Position start,
                   @Nullable
                   Position end)

(Private constructor, use one of the factory methods create(File), create(File, Position, Position), or create(File, String, int, int).

Constructs a new location range for the given file, from start to end. If the length of the range is not known, end may be null.

Parameters:

file - the associated file (but see the documentation for getFile() for more information on what the file represents)

start - the starting position, or null

end - the ending position, or null

Method Detail

getFile

@NonNull
public java.io.File getFile()

Returns the file containing the warning. Note that the file *itself* may not yet contain the error. When editing a file in the IDE for example, the tool could generate warnings in the background even before the document is saved. However, the file is used as a identifying token for the document being edited, and the IDE integration can map this back to error locations in the editor source code.

Returns:

the file handle for the location

getStart

@Nullable
public Position getStart()

The start position of the range

Returns:

the start position of the range, or null

getEnd

@Nullable
public Position getEnd()

The end position of the range

Returns:

the start position of the range, may be null for an empty range

getSecondary

@Nullable
public Location getSecondary()

Returns a secondary location associated with this location (if applicable), or null.

Returns:

a secondary location or null

setSecondary

public void setSecondary(@Nullable
                         Location secondary)

Sets a secondary location for this location.

Parameters:

secondary - a secondary location associated with this location

setMessage

public void setMessage(@NonNull
                       java.lang.String message)

Sets a custom message for this location. This is typically used for secondary locations, to describe the significance of this alternate location. For example, for a duplicate id warning, the primary location might say "This is a duplicate id", pointing to the second occurrence of id declaration, and then the secondary location could point to the original declaration with the custom message "Originally defined here".

Parameters:

message - the message to apply to this location

getMessage

@Nullable
public java.lang.String getMessage()

Returns the custom message for this location, if any. This is typically used for secondary locations, to describe the significance of this alternate location. For example, for a duplicate id warning, the primary location might say "This is a duplicate id", pointing to the second occurrence of id declaration, and then the secondary location could point to the original declaration with the custom message "Originally defined here".

Returns:

the custom message for this location, or null

setClientData

public void setClientData(@Nullable
                          java.lang.Object clientData)

Sets the client data associated with this location. This is an optional field which can be used by the creator of the Location to store temporary state associated with the location.

Parameters:

clientData - the data to store with this location

getClientData

@Nullable
public java.lang.Object getClientData()

Returns the client data associated with this location - an optional field which can be used by the creator of the Location to store temporary state associated with the location.

Returns:

the data associated with this location

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

create

@NonNull
public static Location create(@NonNull
                                      java.io.File file)

Creates a new location for the given file

Parameters:

file - the file to create a location for

Returns:

a new location

create

@NonNull
public static Location create(@NonNull
                                      java.io.File file,
                                      @NonNull
                                      Position start,
                                      @Nullable
                                      Position end)

Creates a new location for the given file and starting and ending positions.

Parameters:

file - the file containing the positions

start - the starting position

end - the ending position

Returns:

a new location

create

@NonNull
public static Location create(@NonNull
                                      java.io.File file,
                                      @Nullable
                                      java.lang.String contents,
                                      int startOffset,
                                      int endOffset)

Creates a new location for the given file, with the given contents, for the given offset range.

Parameters:

file - the file containing the location

contents - the current contents of the file

startOffset - the starting offset

endOffset - the ending offset

Returns:

a new location

create

@NonNull
public static Location create(@NonNull
                                      java.io.File file,
                                      @NonNull
                                      java.lang.String contents,
                                      int line)

Creates a new location for the given file, with the given contents, for the given line number.

Parameters:

file - the file containing the location

contents - the current contents of the file

line - the line number (0-based) for the position

Returns:

a new location

create

@NonNull
public static Location create(@NonNull
                                      java.io.File file,
                                      @NonNull
                                      java.lang.String contents,
                                      int line,
                                      @Nullable
                                      java.lang.String patternStart,
                                      @Nullable
                                      java.lang.String patternEnd,
                                      @Nullable
                                      Location.SearchHints hints)

Creates a new location for the given file, with the given contents, for the given line number.

Parameters:

file - the file containing the location

contents - the current contents of the file

line - the line number (0-based) for the position

patternStart - an optional pattern to search for from the line match; if found, adjust the column and offsets to begin at the pattern start

patternEnd - an optional pattern to search for behind the start pattern; if found, adjust the end offset to match the end of the pattern

hints - optional additional information regarding the pattern search

Returns:

a new location

reverse

public static Location reverse(@NonNull
                               Location location)

Reverses the secondary location list initiated by the given location

Parameters:

location - the first location in the list

Returns:

the first location in the reversed list