public class InputConnectionWrapper extends Object implements InputConnection
Wrapper class for proxying calls to another InputConnection. Subclass and have fun!
CURSOR_UPDATE_IMMEDIATE, CURSOR_UPDATE_MONITOR, GET_EXTRACTED_TEXT_MONITOR, GET_TEXT_WITH_STYLES, INPUT_CONTENT_GRANT_READ_URI_PERMISSION
Constructor and Description |
---|
InputConnectionWrapper(InputConnection target,
boolean mutable)
Initializes a wrapper.
|
Modifier and Type | Method and Description |
---|---|
boolean |
beginBatchEdit()
Tell the editor that you are starting a batch of editor
operations.
|
boolean |
clearMetaKeyStates(int states)
Clear the given meta key pressed states in the given input
connection.
|
void |
closeConnection()
Called by the system up to only once to notify that the system is about to invalidate
connection between the input method and the application.
|
boolean |
commitCompletion(CompletionInfo text)
Commit a completion the user has selected from the possible ones
previously reported to
InputMethodSession#displayCompletions(CompletionInfo[]) or
InputMethodManager#displayCompletions(View, CompletionInfo[]) . |
boolean |
commitContent(InputContentInfo inputContentInfo,
int flags,
Bundle opts)
Called by the input method to commit content such as a PNG image to the editor.
|
boolean |
commitCorrection(CorrectionInfo correctionInfo)
Commit a correction automatically performed on the raw user's input.
|
boolean |
commitText(CharSequence text,
int newCursorPosition)
Commit text to the text box and set the new cursor position.
|
boolean |
deleteSurroundingText(int beforeLength,
int afterLength)
Delete beforeLength characters of text before the
current cursor position, and delete afterLength
characters of text after the current cursor position, excluding
the selection.
|
boolean |
deleteSurroundingTextInCodePoints(int beforeLength,
int afterLength)
A variant of
InputConnection.deleteSurroundingText(int, int) . |
boolean |
endBatchEdit()
Tell the editor that you are done with a batch edit previously
initiated with
InputConnection.beginBatchEdit() . |
boolean |
finishComposingText()
Have the text editor finish whatever composing text is
currently active.
|
int |
getCursorCapsMode(int reqModes)
Retrieve the current capitalization mode in effect at the
current cursor position in the text.
|
ExtractedText |
getExtractedText(ExtractedTextRequest request,
int flags)
Retrieve the current text in the input connection's editor, and
monitor for any changes to it.
|
Handler |
getHandler()
Called by the
InputMethodManager to enable application developers to specify a
dedicated Handler on which incoming IPC method calls from input methods will be
dispatched. |
int |
getMissingMethodFlags() |
CharSequence |
getSelectedText(int flags)
Gets the selected text, if any.
|
CharSequence |
getTextAfterCursor(int n,
int flags)
Get n characters of text after the current cursor
position.
|
CharSequence |
getTextBeforeCursor(int n,
int flags)
Get n characters of text before the current cursor
position.
|
boolean |
performContextMenuAction(int id)
Perform a context menu action on the field.
|
boolean |
performEditorAction(int editorAction)
Have the editor perform an action it has said it can do.
|
boolean |
performPrivateCommand(String action,
Bundle data)
API to send private commands from an input method to its
connected editor.
|
boolean |
reportFullscreenMode(boolean enabled)
Called by the IME to tell the client when it switches between
fullscreen and normal modes.
|
boolean |
requestCursorUpdates(int cursorUpdateMode)
Called by the input method to ask the editor for calling back
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo) to
notify cursor/anchor locations. |
boolean |
sendKeyEvent(KeyEvent event)
Send a key event to the process that is currently attached
through this input connection.
|
boolean |
setComposingRegion(int start,
int end)
Mark a certain region of text as composing text.
|
boolean |
setComposingText(CharSequence text,
int newCursorPosition)
Replace the currently composing text with the given text, and
set the new cursor position.
|
boolean |
setSelection(int start,
int end)
Set the selection of the text editor.
|
void |
setTarget(InputConnection target)
Change the target of the input connection.
|
public InputConnectionWrapper(InputConnection target, boolean mutable)
Caveat: Although the system can accept (InputConnection) null
in some
places, you cannot emulate such a behavior by non-null InputConnectionWrapper
that
has null
in target
.
target
- the InputConnection
to be proxied.mutable
- set true
to protect this object from being reconfigured to target
another InputConnection
. Note that this is ignored while the target is null
.public void setTarget(InputConnection target)
Caveat: Although the system can accept (InputConnection) null
in some
places, you cannot emulate such a behavior by non-null InputConnectionWrapper
that
has null
in target
.
target
- the InputConnection
to be proxied.SecurityException
- when this wrapper has non-null target and is immutable.public int getMissingMethodFlags()
public CharSequence getTextBeforeCursor(int n, int flags)
This method may fail either if the input connection has become invalid (such as its process crashing) or the editor is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned. This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time. Also, please keep in mind the Editor may choose to return less characters than requested even if they are available for performance reasons.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text and use this method right away; you need to make sure the returned value is consistent with the result of the latest edits. Also, you may return less than n characters if performance dictates so, but keep in mind IMEs are relying on this for many functions: you should not, for example, limit the returned value to the current line, and specifically do not return 0 characters unless the cursor is really at the start of the text.
getTextBeforeCursor
in interface InputConnection
n
- The expected length of the text.flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.NullPointerException
- if the target is null
.public CharSequence getTextAfterCursor(int n, int flags)
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned.
This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text and use this method right away; you need to make sure the returned value is consistent with the result of the latest edits. Also, you may return less than n characters if performance dictates so, but keep in mind IMEs are relying on this for many functions: you should not, for example, limit the returned value to the current line, and specifically do not return 0 characters unless the cursor is really at the end of the text.
getTextAfterCursor
in interface InputConnection
n
- The expected length of the text.flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.NullPointerException
- if the target is null
.public CharSequence getSelectedText(int flags)
This method may fail if either the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple of seconds to return). In either case, null is returned.
This method must not cause any changes in the editor's state.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text or change the selection position and use this method right away; you need to make sure the returned value is consistent with the results of the latest edits.
getSelectedText
in interface InputConnection
flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.Build.VERSION_CODES.N
and
later, returns false when the target application does not implement
this method.NullPointerException
- if the target is null
.public int getCursorCapsMode(int reqModes)
TextUtils.getCapsMode
for more information.
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, 0 is returned.
This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
Editor authors: please be careful of race conditions in implementing this call. An IME can change the cursor position and use this method right away; you need to make sure the returned value is consistent with the results of the latest edits and changes to the cursor position.
getCursorCapsMode
in interface InputConnection
reqModes
- The desired modes to retrieve, as defined by
TextUtils.getCapsMode
. These
constants are defined so that you can simply pass the current
TextBoxAttribute.contentType
value
directly in to here.InputType
.NullPointerException
- if the target is null
.public ExtractedText getExtractedText(ExtractedTextRequest request, int flags)
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned.
Editor authors: as a general rule, try to comply with the
fields in request
for how many chars to return,
but if performance or convenience dictates otherwise, please
feel free to do what is most appropriate for your case. Also,
if the
InputConnection.GET_EXTRACTED_TEXT_MONITOR
flag is set, you should be
calling
InputMethodManager.updateExtractedText(View, int, ExtractedText)
whenever you call
InputMethodManager.updateSelection(View, int, int, int, int)
.
getExtractedText
in interface InputConnection
request
- Description of how the text should be returned.
ExtractedTextRequest
flags
- Additional options to control the client, either 0 or
InputConnection.GET_EXTRACTED_TEXT_MONITOR
.ExtractedText
object describing the state of the text view and containing the
extracted text itself, or null if the input connection is no
longer valid of the editor can't comply with the request for
some reason.NullPointerException
- if the target is null
.public boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength)
InputConnection.deleteSurroundingText(int, int)
. Major differences are:
Editor authors: In addition to the requirement in
InputConnection.deleteSurroundingText(int, int)
, make sure to do nothing when one ore more invalid
surrogate pairs are found in the requested range.
deleteSurroundingTextInCodePoints
in interface InputConnection
beforeLength
- The number of characters before the cursor to be deleted, in code points.
If this is greater than the number of existing characters between the beginning of the
text and the cursor, then this method does not fail but deletes all the characters in
that range.afterLength
- The number of characters after the cursor to be deleted, in code points.
If this is greater than the number of existing characters between the cursor and
the end of the text, then this method does not fail but deletes all the characters in
that range.false
when the target application does not implement this method.NullPointerException
- if the target is null
.InputConnection.deleteSurroundingText(int, int)
public boolean deleteSurroundingText(int beforeLength, int afterLength)
The lengths are supplied in Java chars, not in code points or in glyphs.
Since this method only operates on text before and after the selection, it can't affect the contents of the selection. This may affect the composing span if the span includes characters that are to be deleted, but otherwise will not change it. If some characters in the composing span are deleted, the composing span will persist but get shortened by however many chars inside it have been removed.
IME authors: please be careful not to
delete only half of a surrogate pair. Also take care not to
delete more characters than are in the editor, as that may have
ill effects on the application. Calling this method will cause
the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on your service after the batch input is over.
Editor authors: please be careful of race
conditions in implementing this call. An IME can make a change
to the text or change the selection position and use this
method right away; you need to make sure the effects are
consistent with the results of the latest edits. Also, although
the IME should not send lengths bigger than the contents of the
string, you should check the values for overflows and trim the
indices to the size of the contents to avoid crashes. Since
this changes the contents of the editor, you need to make the
changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
deleteSurroundingText
in interface InputConnection
beforeLength
- The number of characters before the cursor to be deleted, in code unit.
If this is greater than the number of existing characters between the beginning of the
text and the cursor, then this method does not fail but deletes all the characters in
that range.afterLength
- The number of characters after the cursor to be deleted, in code unit.
If this is greater than the number of existing characters between the cursor and
the end of the text, then this method does not fail but deletes all the characters in
that range.NullPointerException
- if the target is null
.public boolean setComposingText(CharSequence text, int newCursorPosition)
If there is any composing span currently active, all
characters that it comprises are removed. The passed text is
added in its place, and a composing span is added to this
text. If there is no composing span active, the passed text is
added at the cursor position (removing selected characters
first if any), and a composing span is added on the new text.
Finally, the cursor is moved to the location specified by
newCursorPosition
.
This is usually called by IMEs to add or remove or change
characters in the composing span. Calling this method will
cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors: please keep in mind the
text may be very similar or completely different than what was
in the composing span at call time, or there may not be a
composing span at all. Please note that although it's not
typical use, the string may be empty. Treat this normally,
replacing the currently composing text with an empty string.
Also, be careful with the cursor position. IMEs rely on this
working exactly as described above. Since this changes the
contents of the editor, you need to make the changes known to
the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress. Note that this method can set the cursor position
on either edge of the composing text or entirely outside it,
but the IME may also go on to move the cursor position to
within the composing text in a subsequent call so you should
make no assumption at all: the composing text and the selection
are entirely independent.
setComposingText
in interface InputConnection
text
- The composing text with styles if necessary. If no style
object attached to the text, the default style for composing text
is used. See Spanned
for how to attach style
object to the text. SpannableString
and
SpannableStringBuilder
are two
implementations of the interface Spanned
.newCursorPosition
- The new cursor position around the text. If
> 0, this is relative to the end of the text - 1; if <= 0, this
is relative to the start of the text. So a value of 1 will
always advance you to the position after the full text being
inserted. Note that this means you can't position the cursor
within the text, because the editor can make modifications to
the text you are providing so it is not possible to correctly
specify locations there.NullPointerException
- if the target is null
.public boolean setComposingRegion(int start, int end)
InputConnection.finishComposingText()
has been called. The default style for composing text is used.
The passed indices are clipped to the contents bounds. If
the resulting region is zero-sized, no region is marked and the
effect is the same as that of calling InputConnection.finishComposingText()
.
The order of start and end is not important. In effect, the
region from start to end and the region from end to start is
the same. Editor authors, be ready to accept a start that is
greater than end.
Since this does not change the contents of the text, editors should not call
InputMethodManager.updateSelection(View, int, int, int, int)
and
IMEs should not receive
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
.
This has no impact on the cursor/selection position. It may result in the cursor being anywhere inside or outside the composing region, including cases where the selection and the composing region overlap partially or entirely.
setComposingRegion
in interface InputConnection
start
- the position in the text at which the composing region beginsend
- the position in the text at which the composing region endsBuild.VERSION_CODES.N
and later, false is returned when the
target application does not implement this method.NullPointerException
- if the target is null
.public boolean finishComposingText()
IME authors: be aware that this call may be expensive with some editors.
Editor authors: please note that the cursor may be anywhere in the contents when this is called, including in the middle of the composing span or in a completely unrelated place. It must not move.
finishComposingText
in interface InputConnection
NullPointerException
- if the target is null
.public boolean commitText(CharSequence text, int newCursorPosition)
This method removes the contents of the currently composing
text and replaces it with the passed CharSequence, and then
moves the cursor according to newCursorPosition
. If there
is no composing text when this method is called, the new text is
inserted at the cursor position, removing text inside the selection
if any. This behaves like calling
setComposingText(text, newCursorPosition)
then InputConnection.finishComposingText()
.
Calling this method will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitText
in interface InputConnection
text
- The text to commit. This may include styles.newCursorPosition
- The new cursor position around the text,
in Java characters. If > 0, this is relative to the end
of the text - 1; if <= 0, this is relative to the start
of the text. So a value of 1 will always advance the cursor
to the position after the full text being inserted. Note that
this means you can't position the cursor within the text,
because the editor can make modifications to the text
you are providing so it is not possible to correctly specify
locations there.NullPointerException
- if the target is null
.public boolean commitCompletion(CompletionInfo text)
InputMethodSession#displayCompletions(CompletionInfo[])
or
InputMethodManager#displayCompletions(View, CompletionInfo[])
.
This will result in the same behavior as if the user had
selected the completion from the actual UI. In all other
respects, this behaves like InputConnection.commitText(CharSequence, int)
.
IME authors: please take care to send the
same object that you received through
InputMethodService.onDisplayCompletions(CompletionInfo[])
.
Editor authors: if you never call
InputMethodSession.displayCompletions(CompletionInfo[])
or
InputMethodManager.displayCompletions(View, CompletionInfo[])
then
a well-behaved IME should never call this on your input
connection, but be ready to deal with misbehaving IMEs without
crashing.
Calling this method (with a valid CompletionInfo
object)
will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitCompletion
in interface InputConnection
text
- The committed completion.NullPointerException
- if the target is null
.public boolean commitCorrection(CorrectionInfo correctionInfo)
Calling this method will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitCorrection
in interface InputConnection
correctionInfo
- Detailed information about the correction.Build.VERSION_CODES.N
and later, returns false
when the target application does not implement this method.NullPointerException
- if the target is null
.public boolean setSelection(int start, int end)
Since this moves the cursor, calling this method will cause
the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
This has no effect on the composing region which must stay unchanged. The order of start and end is not important. In effect, the region from start to end and the region from end to start is the same. Editor authors, be ready to accept a start that is greater than end.
setSelection
in interface InputConnection
start
- the character index where the selection should start.end
- the character index where the selection should end.NullPointerException
- if the target is null
.public boolean performEditorAction(int editorAction)
This is typically used by IMEs when the user presses the key associated with the action.
performEditorAction
in interface InputConnection
editorAction
- This must be one of the action constants for
EditorInfo.editorType
, such as
EditorInfo.EDITOR_ACTION_GO
.NullPointerException
- if the target is null
.public boolean performContextMenuAction(int id)
android.R.id#selectAll
,
android.R.id#startSelectingText
, android.R.id#stopSelectingText
,
android.R.id#cut
, android.R.id#copy
,
android.R.id#paste
, android.R.id#copyUrl
,
or android.R.id#switchInputMethod
performContextMenuAction
in interface InputConnection
NullPointerException
- if the target is null
.public boolean beginBatchEdit()
InputConnection.endBatchEdit()
is called. Batch
edits nest.
IME authors: use this to avoid getting
calls to
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
corresponding to intermediate state. Also, use this to avoid
flickers that may arise from displaying intermediate state. Be
sure to call InputConnection.endBatchEdit()
for each call to this, or
you may block updates in the editor.
Editor authors: while a batch edit is in progress, take care not to send updates to the input method and not to update the display. IMEs use this intensively to this effect. Also please note that batch edits need to nest correctly.
beginBatchEdit
in interface InputConnection
NullPointerException
- if the target is null
.public boolean endBatchEdit()
InputConnection.beginBatchEdit()
. This ends the latest
batch only.
IME authors: make sure you call this
exactly once for each call to InputConnection.beginBatchEdit()
.
Editor authors: please be careful about batch edit nesting. Updates still to be held back until the end of the last batch edit.
endBatchEdit
in interface InputConnection
NullPointerException
- if the target is null
.public boolean sendKeyEvent(KeyEvent event)
This method can be used to send key events to the application. For example, an on-screen keyboard may use this method to simulate a hardware keyboard. There are three types of standard keyboards, numeric (12-key), predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type by specify the device id of the key event.
You will usually want to set the flag
KeyEvent.FLAG_SOFT_KEYBOARD
on all key event objects you give to this API; the flag will
not be set for you.
Note that it's discouraged to send such key events in normal
operation; this is mainly for use with
InputType.TYPE_NULL
type text fields. Use
the InputConnection.commitText(java.lang.CharSequence, int)
family of methods to send text to the
application instead.
sendKeyEvent
in interface InputConnection
event
- The key event.NullPointerException
- if the target is null
.KeyEvent
,
KeyCharacterMap.NUMERIC
,
KeyCharacterMap.PREDICTIVE
,
KeyCharacterMap.ALPHA
public boolean clearMetaKeyStates(int states)
This can be used by the IME to clear the meta key states set by a hardware keyboard with latched meta keys, if the editor keeps track of these.
clearMetaKeyStates
in interface InputConnection
states
- The states to be cleared, may be one or more bits as
per KeyEvent.getMetaState()
.NullPointerException
- if the target is null
.public boolean reportFullscreenMode(boolean enabled)
InputMethodService
.reportFullscreenMode
in interface InputConnection
NullPointerException
- if the target is null
.public boolean performPrivateCommand(String action, Bundle data)
EditorInfo
to determine if a client
supports a particular command.performPrivateCommand
in interface InputConnection
action
- Name of the command to be performed. This must
be a scoped name, i.e. prefixed with a package name you own, so that
different developers will not create conflicting commands.data
- Any data to include with the command.NullPointerException
- if the target is null
.public boolean requestCursorUpdates(int cursorUpdateMode)
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)
to
notify cursor/anchor locations.requestCursorUpdates
in interface InputConnection
cursorUpdateMode
- InputConnection.CURSOR_UPDATE_IMMEDIATE
and/or
InputConnection.CURSOR_UPDATE_MONITOR
. Pass 0
to disable the effect of
InputConnection.CURSOR_UPDATE_MONITOR
.true
if the request is scheduled. false
to indicate that when the
application will not call
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)
.
In Build.VERSION_CODES.N
and later, returns false
also when the
target application does not implement this method.NullPointerException
- if the target is null
.public Handler getHandler()
InputMethodManager
to enable application developers to specify a
dedicated Handler
on which incoming IPC method calls from input methods will be
dispatched.
Note: This does nothing when called from input methods.
getHandler
in interface InputConnection
null
to use the default Handler
.NullPointerException
- if the target is null
.public void closeConnection()
Editor authors: You can clear all the nested batch edit right now and
you no longer need to handle subsequent callbacks on this connection, including
InputConnection.beginBatchEdit()
}. Note that although the system tries to call this method whenever
possible, there may be a chance that this method is not called in some exceptional
situations.
Note: This does nothing when called from input methods.
closeConnection
in interface InputConnection
NullPointerException
- if the target is null
.public boolean commitContent(InputContentInfo inputContentInfo, int flags, Bundle opts)
In order to avoid a variety of compatibility issues, this focuses on a simple use case, where editors and IMEs are expected to work cooperatively as follows:
EditorInfo.contentMimeTypes
equal to null
if it does
not support this method at all.inputContentInfo
does not match any of EditorInfo.contentMimeTypes
.
true
asynchronously, even before it starts loading the
content.EditorInfo.packageName
about how to obtain the package name of the editor.commitContent
in interface InputConnection
inputContentInfo
- Content to be inserted.flags
- InputConnection.INPUT_CONTENT_GRANT_READ_URI_PERMISSION
if the content provider
allows grantUriPermissions
or 0
if the application does not need to call
InputContentInfo.requestPermission()
.opts
- optional bundle data. This can be null
.true
if this request is accepted by the application, whether the request
is already handled or still being handled in background, false
otherwise.NullPointerException
- if the target is null
.