public interface Management extends Remote, ManagementMXBean
Interface for a service object that exposes information about the Persistit environment. With this public API, embedding applications can query performance metrics and resources within Persistit that are not exposed by the normal access methods. For example, this class provides methods that enumerate the volumes currently mounted, the size and effectiveness of buffer pool components, and many other items that may be useful in tuning and managing Persistit.
Methods of this class are exposed via RMI (Remote Method Invocation) to permit management tools to operate remotely. For example, the AdminUI tool can connect to a running Persistit instance via RMI. Most of the information available on this interface is also accessible through JMX MXBeans.
Modifier and Type | Interface and Description |
---|---|
static class |
Management.AcquisitionTimeBase
Base class for all management data structures that retain the time at
which the information was recorded.
|
static class |
Management.BufferInfo
Exposes information about one
Buffer . |
static class |
Management.BufferPoolInfo
Exposes information about a BufferPool.
|
static interface |
Management.DisplayFilter
A DisplayFilter formats the String value presented in the Tree tab of the
AdminUI.
|
static class |
Management.JournalInfo
Structure that describes the current state of the journal manager.
|
static class |
Management.LogicalRecord
A structure that contains data about a single logical record within a
page.
|
static class |
Management.LogicalRecordCount
A structure that returns the result of the
getLogicalRecordCount(java.lang.String, java.lang.String, java.lang.String, com.persistit.KeyState, com.persistit.Key.Direction, int)
method. |
static class |
Management.RecordInfo
A structure that contains data about a single physical record within a
page.
|
static class |
Management.RecoveryInfo
A structure that holds information about the recovered database.
|
static class |
Management.TaskStatus
Structure that describes the current status of a long-running utility
task.
|
static class |
Management.TransactionInfo
A structure that holds counts of commit, rollbacks and rollbacks since
the last commit.
|
static class |
Management.TreeInfo
Exposes information about a Persistit
Tree . |
static class |
Management.VolumeInfo
Exposes information about a Volume.
|
static class |
Management.WrappedRemoteException
A subclass of
RemoteException that wraps a
Throwable so that it can be returned to the remote client. |
MXBEAN_NAME
Modifier and Type | Method and Description |
---|---|
boolean |
close()
Attempts to close Persistit by invoking
Persistit.close() . |
Object[] |
decodeKeyObjects(KeyState keyState,
CoderContext context)
Decodes the content of the supplied
KeyState as an array of
Objects, one object per key segment. |
Object[] |
decodeValueObjects(ValueState valueState,
CoderContext context)
Decodes the content of the supplied
ValueState as an array
of Objects. |
Management.BufferInfo |
getBufferInfo(String volumeName,
long pageAddress)
Return a
BufferInfo reflecting the status of the buffer
containing the page specified by the supplied volumeName and
pageAddress . |
Management.BufferInfo |
getBufferInfo(String volumeName,
String treeName,
KeyState key,
int level)
Return a
BufferInfo reflecting the state of a page
containing the specified key. |
Management.BufferInfo[] |
getBufferInfoArray(int bufferSize,
int traversalType,
String includeMask,
String excludeMask)
Return an array of
Management.BufferInfo objects reflecting the states of
selected buffers from the BufferPool for the specified
bufferSize . |
Management.BufferPoolInfo[] |
getBufferPoolInfoArray()
Return an array containing a
BufferPoolInfo element for each
buffer pool. |
Management.DisplayFilter |
getDisplayFilter() |
Management.JournalInfo |
getJournalInfo()
Return a
Management.JournalInfo structure describing the current state of
the Journal. |
Management.LogicalRecord[] |
getLogicalRecordArray(String volumeName,
String treeName,
String keyFilterString,
KeyState fromKey,
Key.Direction direction,
int maxRecordCount,
int maxValueBytes,
boolean decodeStrings)
Return an array of
LogicalRecord elements from a
Tree . |
Management.LogicalRecordCount |
getLogicalRecordCount(String volumeName,
String treeName,
String keyFilterString,
KeyState fromKey,
Key.Direction direction,
int maximumCount)
Count the the number of records that could be traversed given a starting
key value in a tree specified by
volumeName ,
treeName , using an optional KeyFilter specified by
keyFilterString . |
Map<ObjectName,Object> |
getMXBeans()
Return an unmodifiable map of all MXBeans registered in the Persistit
instance.
|
Management.RecordInfo[] |
getRecordInfoArray(String volumeName,
long pageAddress)
Return an array containing a
RecordInfo element for each
record in the page specified by volumeName and
pageAddress . |
Management.RecoveryInfo |
getRecoveryInfo()
Return a
Management.RecoveryInfo structure describing the current state of
the recovery process. |
Class<?> |
getRemoteClass(String className)
Return a Class definition for a class specified by its name.
|
Management.TransactionInfo |
getTransactionInfo()
Return a
Management.TransactionInfo structure summarizing Transaction commit
and rollback information. |
Management.TreeInfo |
getTreeInfo(String volumeName,
String treeName)
Return a
TreeInfo for a specified Volume and
Tree . |
Management.TreeInfo[] |
getTreeInfoArray(String volumeName)
Return an array containing a
TreeInfo element for each
Tree in the specified volume. |
Management.VolumeInfo |
getVolumeInfo(String volumeName)
Return the
VolumeInfo for the volume specified by the
supplied volumeName . |
Management.VolumeInfo[] |
getVolumeInfoArray()
Return an array containing a
VolumeInfo element for each
open volume. |
String |
launch(Task task,
String description)
Launch a task.
|
int |
parseKeyFilterString(String keyFilterString)
Parse the supply String to determine whether it is a valid
KeyFilter and return the index of the first incorrect
character in the supplied String, or -1 if the string is a valid String
representation of a KeyFilter. |
int |
populateBufferInfoArray(Management.BufferInfo[] results,
int bufferSize,
int traversalType,
String includeMask,
String excludeMask)
Populates a supplied array of
Management.BufferInfo objects to reflect the
current states of selected buffers from the BufferPool for
the specified bufferSize . |
Management.TaskStatus[] |
queryTaskStatus(long taskId,
boolean details,
boolean clearMessages)
Queries the current status of one or all tasks.
|
Management.TaskStatus[] |
queryTaskStatus(long taskId,
boolean details,
boolean clearMessages,
boolean clearTasks)
Queries the current status of one or all tasks.
|
void |
removeFinishedTasks(long taskId)
Removes done, expired, stopped or failed tasks from the task list.
|
void |
setAppendOnly(boolean suspended)
Controls whether Persistit suspends the thread that copies pages from the
journal back to their respective Volumes.
|
void |
setDisplayFilter(Management.DisplayFilter displayFilter) |
void |
setJournalCopyingFast(boolean fast)
Controls whether Persistit copies page from the journal back to their
volumes as fast as possible.
|
void |
setTaskSuspended(long taskId,
boolean suspend)
Suspend or resume the task(s) identified by
taskId . |
long |
startTask(String description,
String owner,
String commandLine,
long maximumTime,
int verbosity)
Starts a long-running utility task, such as the integrity checker.
|
void |
stopTask(long taskId,
boolean remove)
Stops and optionally removes a task specified by its id value.
|
execute, flushAndForce, getCommittedTransactionCount, getCopyright, getDefaultCommitPolicy, getElapsedTime, getRmiPort, getRollbackCount, getStartTime, getVersion, getVolumes, isInitialized, isShutdownSuspended, isUpdateSuspended, launch, setDefaultCommitPolicy, setShutdownSuspended, setUpdateSuspended, transactionReport, volumeByName
void setAppendOnly(boolean suspended) throws RemoteException
suspended
- true
to specify that Persistit will suspend
journal copying; otherwise false
.RemoteException
void setJournalCopyingFast(boolean fast) throws RemoteException
fast
- true
to copy pages at maximum speed.RemoteException
boolean close() throws RemoteException
Persistit.close()
.true
if the attempt to close Persistit was
successful; otherwise false
RemoteException
Management.BufferPoolInfo[] getBufferPoolInfoArray() throws RemoteException
BufferPoolInfo
element for each
buffer pool. If Persistit is not initialized then this method returns an
empty array.RemoteException
Management.RecordInfo[] getRecordInfoArray(String volumeName, long pageAddress) throws RemoteException
RecordInfo
element for each
record in the page specified by volumeName
and
pageAddress
. If Persistit is not initialized, or if there is
no unique Volume
for the specified volumeName
,
or if there is no page associated with the specified
pageAddress
or if there is any transient condition that
causes the attempt to retrieve records to fail, then this method returns
an empty array.volumeName
- The volume namepageAddress
- The page addresRecordInfo
objects containing
detailed information about the records on the specified page.RemoteException
Management.LogicalRecord[] getLogicalRecordArray(String volumeName, String treeName, String keyFilterString, KeyState fromKey, Key.Direction direction, int maxRecordCount, int maxValueBytes, boolean decodeStrings) throws RemoteException
Return an array of LogicalRecord
elements from a
Tree
. The tree is specified by the provided
volumeName
and treeName
values. The size of the
the returned array is bounded by maxRecordCount
. Records
whose Value
fields exceed maxValueBytes
in
length are truncated to that size. This allows a client program to limit
the maximum number of bytes to be transmitted in one RMI request. If non-
null
, keyFilterString
specifies a
KeyFilter
to be applied when taversing records. The supplied
fromKey
specifies a starting key value, and is non-
inclusive.
Each LogicalRecord
object returned by this method optionally
contain decoded String representations of the record's key and value. If
decodeString
is true
then each
LogicalRecord
's KeyState
,
KeyString
and ValueString
properties are set to
String values resulting from decoding the underlying key and value in the
context of the running Persistit instance. Otherwise,
KeyString
and ValueString
are null
. Applications that display String-valued representations of a record's
key and value should typically enable decodeString
so that
any required KeyCoder
or
ValueCoder
objects are referenced in the
context of the running Persistit instance, not an RMI client.
volumeName
- The volume nametreeName
- The tree namekeyFilterString
- If non-null
, specifies the String representation
of a KeyFilter
. Only records having key values
selected by this filter are returned.fromKey
- Starting key value.direction
- Traversal direction.maxRecordCount
- Maximum number of LogicalRecord objects to returnmaxValueBytes
- Maximum encoded size of each Value object.decodeStrings
- If true
, decode each LogicalRecord
's
Key
and Value
as Strings.RemoteException
Management.JournalInfo getJournalInfo() throws RemoteException
Management.JournalInfo
structure describing the current state of
the Journal.RemoteException
Management.RecoveryInfo getRecoveryInfo() throws RemoteException
Management.RecoveryInfo
structure describing the current state of
the recovery process.RemoteException
Management.TransactionInfo getTransactionInfo() throws RemoteException
Management.TransactionInfo
structure summarizing Transaction commit
and rollback information.RemoteException
Management.LogicalRecordCount getLogicalRecordCount(String volumeName, String treeName, String keyFilterString, KeyState fromKey, Key.Direction direction, int maximumCount) throws RemoteException
Count the the number of records that could be traversed given a starting
key value in a tree specified by volumeName
,
treeName
, using an optional KeyFilter
specified by
keyFilterString
. Records are counted by traversing forward
or backward according to the Persistit key order specification. The direction
of traversal is specified by direction
.
The returned LogicalRecordCount
contains the count of
records actually traversed by this method, which will never exceed
maximumCount
. It also contains a KeyState
representing the value of the Key
of the final record
traversed by this method. If the returned count is N then the returned
KeyState
corresponds with the Nth record counted.
volumeName
- The volume nametreeName
- The tree namekeyFilterString
- If non-null
, specifies the String representation
of a KeyFilter
. Only records having key values
selected by this filter are returned.fromKey
- Starting key value.direction
- Traversal direction.maximumCount
- Maximum number of LogicalRecord objects to traverse.RemoteException
Management.BufferInfo[] getBufferInfoArray(int bufferSize, int traversalType, String includeMask, String excludeMask) throws RemoteException
Return an array of Management.BufferInfo
objects reflecting the states of
selected buffers from the BufferPool
for the specified
bufferSize
. The selection criteria include the
traversalType
, includeMask
and
excludeMask
. See populateBufferInfoArray(com.persistit.Management.BufferInfo[], int, int, java.lang.String, java.lang.String)
for a
similar method that reuses a previously obtained result array.
The traversalType
must be one of the following:
poolIndex
.
The includeMask
and excludeMask
are applied to
each buffer's state to determine whether that buffer should be included
in the set returned by this method. If includeMask
is
null
then all buffers are included. Otherwise, only those
buffers whose state is selected by includeMask
and is not
selected by excludeMask
are included. Mask values are
Strings in which each character denotes an attribute of a
Buffer
to be included or excluded from the selection. These
characters are as follows:
Volume
occupies a PERMANENT buffer.If Persistit is not initialized then this method returns an empty array.
bufferSize
- the buffer size of interesttraversalType
- the traversal type, described aboveincludeMask
- the buffer selection include mask, described aboveexcludeMask
- the buffer selection exclude mask, described aboveRemoteException
Management.BufferInfo getBufferInfo(String volumeName, long pageAddress) throws RemoteException
BufferInfo
reflecting the status of the buffer
containing the page specified by the supplied volumeName
and
pageAddress
. If Persisit is not initialized or of the
attempt the find the specified page fails, this method returns
null
volumeName
- the name of the volumepageAddress
- the page addressnull
if there is none.RemoteException
Management.BufferInfo getBufferInfo(String volumeName, String treeName, KeyState key, int level) throws RemoteException
BufferInfo
reflecting the state of a page
containing the specified key. The volumeName
and
treeName
parameters specify a Tree
in which to seach
for the key. The level
parameter indicates whether the data
page, or one of the pages on the index path to that data page should be
returned. Level 0 refers to the data path, level 1 is the lowest index
level, and level d-1 where d is the number of levels in the the tree
represents the three's root page.
Specify treeName
as null
to access the volume's
directory tree.
volumeName
- the name of the volumetreeName
- the name of the tree within the volume, or null
for the directory treekey
- a KeyState
representing a keylevel
- tree level: 0 for root, 1...d-1 for index pages of a tree
having depth d.BufferInfo
object reflecting the selected page, or
null
if the specified tree does not exist.RemoteException
int populateBufferInfoArray(Management.BufferInfo[] results, int bufferSize, int traversalType, String includeMask, String excludeMask) throws RemoteException
Populates a supplied array of Management.BufferInfo
objects to reflect the
current states of selected buffers from the BufferPool
for
the specified bufferSize
. The selection criteria include the
traversalType
, includeMask
and
excludeMask
. See getBufferInfoArray(int, int, java.lang.String, java.lang.String)
for a similar
method that simply returns a fresh array on each invocation. This method
is available for management applications that need to perform frequently
refreshes.
This method returns the actual number of buffers selected by the supplied
criteria. This number may be larger than the size of the supplied array;
in this case, information about the first N buffers in the set is
returned in the array, where N is the size of the array. An application
can use the Management.BufferPoolInfo.getBufferCount()
method to determine the
maximum number of BufferInfo
objects that could be
populated.
The traversalType
must be one of the following:
poolIndex
.
The includeMask
and excludeMask
are applied to
each buffer's state to determine whether that buffer should be included
in the set returned by this method. If includeMask
is
null
then all buffers are included. Otherwise, only those
buffers whose state is selected by includeMask
and is not
selected by excludeMask
are included. Mask values are
Strings in which each character denotes an attribute of a
Buffer
to be included or excluded from the selection. These
characters are as follows:
Volume
occupies a PERMANENT buffer.If Persistit is not initialized then this method returns an empty array.
bufferSize
- the buffer size of interesttraversalType
- the traversal type, described aboveincludeMask
- the buffer selection include mask, described aboveexcludeMask
- the buffer selection exclude mask, described aboveRemoteException
Management.VolumeInfo[] getVolumeInfoArray() throws RemoteException
VolumeInfo
element for each
open volume. If Persistit is not initialized then this method returns an
empty array. RemoteException
Class<?> getRemoteClass(String className) throws RemoteException
ClassLoader
instance so that unreferenced
loaded classes may subsequently be garbage collected.className
- Fully qualified class name.Class
, or null
if an exception
occurred while attempting to acquire the Class.RemoteException
Management.VolumeInfo getVolumeInfo(String volumeName) throws RemoteException
VolumeInfo
for the volume specified by the
supplied volumeName
. If Persisit is not initialized or there
is no unique volume corresponding with the supplied name, then this
method returns null
.volumeName
- VolumeInfo
RemoteException
Management.TreeInfo[] getTreeInfoArray(String volumeName) throws RemoteException
TreeInfo
element for each
Tree
in the specified volume. If there is no volume with the
specified name or if Persistit is not initialized then this method
returns an empty array.volumeName
- The name (or unique partial name) of the volume for which
information is being requested.RemoteException
Management.TreeInfo getTreeInfo(String volumeName, String treeName) throws RemoteException
TreeInfo
for a specified Volume
and
Tree
. If Persisit is not initialized, or if no no volume or
tree with corresponding names is found, or if there is a transient error
in acquiring the information, this method returns null
.volumeName
- The name (or partial name) of the volumetreeName
- The name of the treeTreeInfo
RemoteException
int parseKeyFilterString(String keyFilterString) throws RemoteException
KeyFilter
and return the index of the first incorrect
character in the supplied String, or -1 if the string is a valid String
representation of a KeyFilter.keyFilterString
- keyFilterString
, or -1 if the string is valid.RemoteException
Object[] decodeValueObjects(ValueState valueState, CoderContext context) throws RemoteException
Decodes the content of the supplied ValueState
as an array
of Objects. Usually this array has one element containing the single
object value encoded in the ValueState
. However, if multiple
items were written to the original Value
from which the
ValueState
was derived in Stream Mode, this method returns all of
the encoded objects.
If the valueState
represents an undefined value, this method
returns an array of length zero. If the valueState
encodes a
value of null
, then this method returns an array containing
one element which is null
.
valueState
- Representation of an encoded Value
.context
- Object passed to any ValueCoder
used in decoding the value. May be null
.RemoteException
Object[] decodeKeyObjects(KeyState keyState, CoderContext context) throws RemoteException
KeyState
as an array of
Objects, one object per key segment.keyState
- Representation of an encoded Key
.context
- Object passed to any KeyCoder
used in decoding the value. May be null
RemoteException
long startTask(String description, String owner, String commandLine, long maximumTime, int verbosity) throws RemoteException
Task
. The number and format of the arguments is specific to the utility task.
The returned long value is a unique task ID value used in subsequent
calls to queryTaskStatus(long, boolean, boolean)
.description
- Readable description of this taskowner
- Hostname or username of the user who requested this taskcommandLine
- command name followed by task-specific parameters delimited by
spaces.maximumTime
- Maximum wall-clock time (in milliseconds) this Task will be
allowed to runverbosity
- Verbosity level, one of Task.LOG_NORMAL
or
Task.LOG_VERBOSE
.RemoteException
String launch(Task task, String description) throws RemoteException
task
- the Taskdescription
- description identifying what the task is doingRemoteException
Management.TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearMessages) throws RemoteException
taskId
- Task ID for a selected Task, or -1 for all Tasks.details
- true
to populate each returned
TaskStatus
object with all new messages posted by
the task.clearMessages
- true
to clear all received messages from the
task.TaskStatus
objects indicating status of
selected task(s).RemoteException
Management.TaskStatus[] queryTaskStatus(long taskId, boolean details, boolean clearMessages, boolean clearTasks) throws RemoteException
taskId
- Task ID for a selected Task, or -1 for all Tasks.details
- true
to populate each returned
TaskStatus
object with all new messages posted by
the task.clearMessages
- true
to clear all received messages from the
task.clearTasks
- true
to clear all completed tasks after reporting
statusTaskStatus
objects indicating status of
selected task(s).RemoteException
void setTaskSuspended(long taskId, boolean suspend) throws RemoteException
taskId
. If
taskId
is -1, all tasks are modified.taskId
- Task ID for a selected Task, or -1 for all Tasks.suspend
- true
to suspend the task, false
to
allow it to resume.RemoteException
void stopTask(long taskId, boolean remove) throws RemoteException
remove
is true
this method also removes the Task from the task
list. Otherwise the task remains on the task list in the
Task.STATE_ENDED
state. If taskId
is -1 then these
actions are applied to all tasks.taskId
- Task ID for a selected Task, or -1 for all Tasks.RemoteException
void removeFinishedTasks(long taskId) throws RemoteException
taskId
- Task ID for a selected task, or -1 for all tasks.RemoteException
Management.DisplayFilter getDisplayFilter() throws RemoteException
RemoteException
void setDisplayFilter(Management.DisplayFilter displayFilter) throws RemoteException
RemoteException
Map<ObjectName,Object> getMXBeans() throws RemoteException
ObjectName on =
new ObjectName(JournalManagerMXBean.MXBEAN_NAME);
For BufferPoolMXBean instances, use
ObjectName on =
new ObjectName(BufferPoolMXBean.MXBEAN_NAME + "." + bufferSize);
RemoteException
Copyright © 2025 Open Identity Platform Community. All rights reserved.