@Beta
public class Location
extends java.lang.Object
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.
Modifier and Type | Class and Description |
---|---|
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, CharSequence, int, String, String, SearchHints) |
Modifier and Type | Field and Description |
---|---|
static Location |
NONE
Special marker location which means location not available, or not applicable, or filtered
out, etc.
|
Modifier | Constructor and Description |
---|---|
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, CharSequence, int, int) . |
Modifier and Type | Method and Description |
---|---|
static Location |
create(java.io.File file)
Creates a new location for the given file
|
static Location |
create(java.io.File file,
java.lang.CharSequence 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.CharSequence 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.
|
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,
com.android.ide.common.blame.SourcePosition position)
Creates a new location for the given file and SourcePosition.
|
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.
|
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.
|
java.lang.Object |
getSource()
Returns the source element for this location, if applicable
|
<T> T |
getSource(java.lang.Class<T> clz)
Returns the source element for this location provided it's of the given type, if applicable
|
Position |
getStart()
The start position of the range
|
boolean |
isSelfExplanatory()
Whether this message is self-explanatory.
|
boolean |
isVisible()
Whether this location should be visible on its own.
|
static Location |
reverse(Location location)
Reverses the secondary location list initiated by the given location
|
Location |
setClientData(java.lang.Object clientData)
Sets the client data associated with this location.
|
Location |
setMessage(java.lang.String message)
Sets a custom message for this location.
|
Location |
setMessage(java.lang.String message,
boolean selfExplanatory)
Sets a custom message for this location.
|
Location |
setSecondary(Location secondary)
Sets a secondary location for this location.
|
Location |
setSelfExplanatory(boolean selfExplanatory)
Sets whether this message is self-explanatory.
|
Location |
setSource(java.lang.Object source)
Sets the source element applicable for this location, if any
|
Location |
setVisible(boolean visible)
Sets whether this location should be visible on its own.
|
java.lang.String |
toString() |
Location |
withSecondary(Location secondary,
java.lang.String message)
Sets a secondary location with the given message and returns the current location
updated with the given secondary location.
|
Location |
withSecondary(Location secondary,
java.lang.String message,
boolean selfExplanatory)
Sets a secondary location with the given message and returns the current location
updated with the given secondary location.
|
public static final Location NONE
NONE
if you ask JavaParser.getLocation(JavaContext, PsiElement)
for an element which is not in the current
file during an incremental lint run in a single file.protected Location(@NonNull java.io.File file, @Nullable Position start, @Nullable Position end)
create(File)
,
create(File, Position, Position)
, or
create(File, CharSequence, 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.
file
- the associated file (but see the documentation for
getFile()
for more information on what the file
represents)start
- the starting position, or nullend
- the ending position, or nullpublic boolean isVisible()
For visible locations, especially those that appear far away from the primary location, it's important that the error message make sense on its own. For example, for duplicate declarations, usually the primary error message says something like "foo has already been defined", and the secondary error message says "previous definition here". In something like a text or HTML report, this makes sense -- you see the "foo has already been defined" error message, and it also reports the locations of the previous error message. But if the secondary error message is visible, the user may encounter that error first, and if that error message just says "previous definition here", that doesn't make a lot of sense.
This attribute is ignored for the primary location for an issue (e.g. the location
passed to
LintClient.report(Context, Issue, Severity, Location, String, TextFormat, Object)
,
and it applies for all the secondary locations linked from that location.
@NonNull public Location setVisible(boolean visible)
isVisible()
.visible
- whether this location should be visible@NonNull public java.io.File getFile()
@Nullable public Position getStart()
@Nullable public Position getEnd()
@Nullable public Location getSecondary()
public Location setSecondary(@Nullable Location secondary)
secondary
- a secondary location associated with this location@NonNull public Location withSecondary(@NonNull Location secondary, @NonNull java.lang.String message)
secondary
- a secondary location associated with this locationmessage
- a message to be set on the secondary location@NonNull public Location withSecondary(@NonNull Location secondary, @NonNull java.lang.String message, boolean selfExplanatory)
secondary
- a secondary location associated with this locationmessage
- a message to be set on the secondary locationselfExplanatory
- if true, the message is itself self-explanatory; see
isSelfExplanatory()
}@Nullable public java.lang.Object getSource()
@Nullable public <T> T getSource(@NonNull java.lang.Class<T> clz)
clz
- the type of the sourcepublic Location setSource(@Nullable java.lang.Object source)
source
- the sourcepublic Location setMessage(@NonNull java.lang.String message)
message
- the message to apply to this locationpublic Location setMessage(@NonNull java.lang.String message, boolean selfExplanatory)
message
- the message to apply to this locationselfExplanatory
- if true, the message is itself self-explanatory;
if false, it's just describing this particular
location and the primary error message is
necessary. Controls whether (for example) the
IDE will include the original error message along
with this location when showing the message.public boolean isSelfExplanatory()
@NonNull public Location setSelfExplanatory(boolean selfExplanatory)
isSelfExplanatory()
.selfExplanatory
- whether this message is self explanatory.@Nullable public java.lang.String getMessage()
public Location setClientData(@Nullable java.lang.Object clientData)
Location
to store
temporary state associated with the location.clientData
- the data to store with this location@Nullable public java.lang.Object getClientData()
Location
to store
temporary state associated with the location.public java.lang.String toString()
toString
in class java.lang.Object
@NonNull public static Location create(@NonNull java.io.File file)
file
- the file to create a location for@NonNull public static Location create(@NonNull java.io.File file, @NonNull com.android.ide.common.blame.SourcePosition position)
file
- the file containing the positionsposition
- the source position@NonNull public static Location create(@NonNull java.io.File file, @NonNull Position start, @Nullable Position end)
file
- the file containing the positionsstart
- the starting positionend
- the ending position@NonNull public static Location create(@NonNull java.io.File file, @Nullable java.lang.CharSequence contents, int startOffset, int endOffset)
file
- the file containing the locationcontents
- the current contents of the filestartOffset
- the starting offsetendOffset
- the ending offset@NonNull public static Location create(@NonNull java.io.File file, @NonNull java.lang.String contents, int line)
file
- the file containing the locationcontents
- the current contents of the fileline
- the line number (0-based) for the position@NonNull public static Location create(@NonNull java.io.File file, @NonNull java.lang.CharSequence contents, int line, @Nullable java.lang.String patternStart, @Nullable java.lang.String patternEnd, @Nullable Location.SearchHints hints)
file
- the file containing the locationcontents
- the current contents of the fileline
- the line number (0-based) for the positionpatternStart
- an optional pattern to search for from the line
match; if found, adjust the column and offsets to begin at the
pattern startpatternEnd
- an optional pattern to search for behind the start
pattern; if found, adjust the end offset to match the end of
the patternhints
- optional additional information regarding the pattern search