public interface IBuffer extends ISnapshotProvider, IReferenceCountable
Clients can take a snapshot of the buffer, construct an edit tree based on the snapshot, and apply the change back to the buffer. Note that an update conflict may occur if the buffer's contents have changed since the inception of the base snapshot.
Buffers support IReferenceCountable
protocol; clients need to follow
the requirements set forth in that protocol. In particular, it is the client
responsibility to release a buffer after it is no longer needed.
Buffers are generally designed to be safe for use by multiple threads. Each buffer implementation is expected to clearly document thread-safety guarantees it provides.
Modifier and Type | Method and Description |
---|---|
default void |
addListener(IBufferListener listener)
Adds the given listener to this buffer.
|
void |
addRef()
Spawns a new independent ownership of this object.
|
IBufferChange |
applyChange(IBufferChange change,
org.eclipse.core.runtime.IProgressMonitor monitor)
Applies the given change to this buffer.
|
default org.eclipse.jface.text.source.IAnnotationModel |
getAnnotationModel()
Returns the annotation model of this buffer, if any.
|
org.eclipse.jface.text.IDocument |
getDocument()
Returns the underlying document of this buffer.
|
ISnapshot |
getSnapshot()
Returns the current snapshot of this buffer.
|
default int |
getSupportedListenerMethods()
Returns a bit-mask describing the listener methods supported
by this buffer.
|
boolean |
isDirty()
Returns whether this buffer has been modified since the last time
it was opened or saved.
|
void |
release()
Relinquishes an independent ownership of this object.
|
default void |
removeListener(IBufferListener listener)
Removes the given listener from this buffer.
|
void |
save(IContext context,
org.eclipse.core.runtime.IProgressMonitor monitor)
Saves this buffer.
|
close
ISnapshot getSnapshot()
Note that it is possible to obtain a non-expiring
snapshot from the buffer, although protractedly holding on non-expiring
snapshots is not recommended as they may potentially consume large amount
of space.
getSnapshot
in interface ISnapshotProvider
null
)IBufferChange applyChange(IBufferChange change, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
Note that an update conflict may occur if the buffer's contents have
changed since the inception of the snapshot on which the change is based.
In that case, a StaleSnapshotException
is thrown.
change
- a buffer change (not null
)monitor
- a progress monitor, or null
if progress reporting is not desired. The caller must not rely on
IProgressMonitor.done()
having been called by the receivernull
StaleSnapshotException
- if the buffer's contents have changed
since the inception of the snapshot on which the change is basedorg.eclipse.core.runtime.CoreException
- if the change's edit tree is not in a valid state,
or if one of the edits in the tree could not be executed, or if save
is requested by the change but the buffer could not be savedvoid save(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
context
- the operation context (not null
)monitor
- a progress monitor, or null
if progress reporting is not desired. The caller must not rely on
IProgressMonitor.done()
having been called by the receiverorg.eclipse.core.runtime.CoreException
- if the buffer could not be savedboolean isDirty()
true
if the buffer has unsaved changes,
false
otherwiseorg.eclipse.jface.text.IDocument getDocument()
null
)default org.eclipse.jface.text.source.IAnnotationModel getAnnotationModel()
null
if nonedefault int getSupportedListenerMethods()
IBufferListener
default void addListener(IBufferListener listener)
listener
- not null
default void removeListener(IBufferListener listener)
listener
- not null
void addRef()
IReferenceCountable
addRef()
must ultimately be
followed by exactly one call to IReferenceCountable.release()
.addRef
in interface IReferenceCountable
addRef
in interface ISnapshotProvider
void release()
IReferenceCountable
release
in interface IReferenceCountable
release
in interface ISnapshotProvider
IReferenceCountable.close()
Copyright (c) 2014, 2020 1C-Soft LLC and others. Made available under the Eclipse Public License 2.0