Interface ResourceHandle
- All Superinterfaces:
Rebindable
- All Known Implementing Classes:
AbstractResourceHandle, PathHandle, StringHandle, UrlHandle
Handles encapsulate the details of how to read, write, and identify the source content (e.g., local files, IDE objects, or memory strings).
Virtual vs. Physical: Use isVirtual() to distinguish between
memory-backed content (snippets, tool args) and persistent storage (files).
- Author:
- anahata
-
Method Summary
Modifier and TypeMethodDescriptiondefault byte[]asBytes()Returns the full content of the resource as a byte array.default StringasText()Returns the full content of the resource as a String.default voiddispose()Performs any necessary cleanup (e.g., removing listeners).booleanexists()Checks if the resource physically or virtually exists.default CharsetReturns the detected or configured charset.default VcsDiffReturns the structured diff between the current working state of this resource and the repository HEAD or pristine base revision.default StringReturns a machine-readable header summarizing the connectivity state.default List<HistoryEntry> getHistory(int maxEntries) Returns the recent version control and local history entries for this resource.default StringReturns an optional HTML-formatted display name.longReturns the last modified timestamp in milliseconds.Returns the detected MIME type of the resource.getName()Returns a user-friendly name for the source.getOwner()Gets the parent resource orchestrator for this handle.getUri()Gets the unique URI for this resource.default booleanChecks whether the underlying resource has unsaved in-memory modifications in the active host environment (e.g., an open NetBeans/IntelliJ editor tab).default booleanisStale(long lastLoadTimestamp) Checks if the source has changed since the last load timestamp.default booleanDetermines if the resource is textual and suitable for a TextView.booleanDetermines if this is a virtual, memory-backed handle.default booleanDetermines if the resource is writable in the current environment.default longlength()Returns the total length of the resource content in characters/bytes.Opens a fresh input stream to the resource content.voidAssociates this handle with its parent Resource.default voidAgnostically writes text content back to the resource with a descriptive reason.Methods inherited from interface Rebindable
rebindModifier and TypeMethodDescriptionvoidrebind()Re-initializes the object's state after deserialization.
-
Method Details
-
getUri
-
getName
-
getHtmlDisplayName
Returns an optional HTML-formatted display name. Used by IDE environments to show status (e.g. Git colors).- Returns:
- The HTML display name, or null.
-
getMimeType
String getMimeType()Returns the detected MIME type of the resource.- Returns:
- The MIME type string (e.g., "text/plain", "image/png").
-
getLastModified
long getLastModified()Returns the last modified timestamp in milliseconds.- Returns:
- The timestamp, or 0 if unknown.
-
exists
boolean exists()Checks if the resource physically or virtually exists.- Returns:
- true if the source is available.
-
openStream
Opens a fresh input stream to the resource content.- Returns:
- A new InputStream instance.
- Throws:
IOException- if the stream cannot be opened.
-
asText
Returns the full content of the resource as a String.Handy API: This uses the handle's detected charset and ensures proper stream closure.
- Returns:
- The text content.
- Throws:
IOException- if reading fails.
-
asBytes
Returns the full content of the resource as a byte array.- Returns:
- The binary content.
- Throws:
IOException- if reading fails.
-
isWritable
default boolean isWritable()Determines if the resource is writable in the current environment.- Returns:
- true if the handle supports the
write(String, String)operation.
-
write
Agnostically writes text content back to the resource with a descriptive reason.Purity Note: Read-only handles should throw
UnsupportedOperationException.- Parameters:
content- The text to write.reason- The reason or explanation for this modification, used for version control or local history labels.- Throws:
IOException- if the write fails.
-
isVirtual
boolean isVirtual()Determines if this is a virtual, memory-backed handle.High-Fidelity Strategy: Virtual handles (snippets) typically trigger the 'Preview-as-Editor' mode in viewers to ensure constant IDE fidelity without card-swapping.
- Returns:
- true if virtual (in-memory content).
-
getCharset
Returns the detected or configured charset. Defaults to UTF-8.- Returns:
- The Charset to use for text interpretation.
-
isStale
default boolean isStale(long lastLoadTimestamp) Checks if the source has changed since the last load timestamp.- Parameters:
lastLoadTimestamp- The timestamp of the last successful load.- Returns:
- true if the source is newer than the timestamp.
-
isModified
default boolean isModified()Checks whether the underlying resource has unsaved in-memory modifications in the active host environment (e.g., an open NetBeans/IntelliJ editor tab).- Returns:
- true if the resource has unsaved modifications in memory, false otherwise.
-
getDiffToHead
-
getHistory
Returns the recent version control and local history entries for this resource.- Parameters:
maxEntries- Maximum number of history entries to return.- Returns:
- A list of
HistoryEntryDTOs, or an empty list if unsupported.
-
isTextual
default boolean isTextual()Determines if the resource is textual and suitable for a TextView.This method provides a centralized capability check. It whitelists common structured data formats that may be classified under the 'application/' hierarchy but are inherently textual.
- Returns:
- true if the resource should be handled by a TextView.
-
getHeader
Returns a machine-readable header summarizing the connectivity state.Technical Purity: The first line always contains the implementation class FQN. The second line provides a comma-separated list of common attributes. Subclasses should override this to append implementation-specific details.
- Returns:
- The header string.
-
setOwner
Associates this handle with its parent Resource.- Parameters:
owner- The owning Resource orchestrator.
-
getOwner
Resource getOwner()Gets the parent resource orchestrator for this handle.- Returns:
- The owning Resource instance.
-
dispose
default void dispose()Performs any necessary cleanup (e.g., removing listeners). -
length
default long length()Returns the total length of the resource content in characters/bytes.- Returns:
- The length, or -1 if the length is unknown or streaming.
-

