Interface ResourceHandle

All Superinterfaces:
Rebindable
All Known Implementing Classes:
AbstractResourceHandle, NbHandle, PathHandle, StringHandle, UrlHandle
public interface ResourceHandle extends Rebindable
A strategy interface for physical or virtual connectivity to resource data.

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 Type
    Method
    Description
    default byte[]
    asBytes()
    Returns the full content of the resource as a byte array.
    default String
    asText()
    Returns the full content of the resource as a String.
    default void
    dispose()
    Performs any necessary cleanup (e.g., removing listeners).
    boolean
    exists()
    Checks if the resource physically or virtually exists.
    default Charset
    getCharset()
    Returns the detected or configured charset.
    default String
    getHeader()
    Returns a machine-readable header summarizing the connectivity state.
    default String
    getHtmlDisplayName()
    Returns an optional HTML-formatted display name.
    long
    getLastModified()
    Returns the last modified timestamp in milliseconds.
    String
    getMimeType()
    Returns the detected MIME type of the resource.
    String
    getName()
    Returns a user-friendly name for the source.
    Resource
    getOwner()
    Gets the parent resource orchestrator for this handle.
    URI
    getUri()
    Gets the unique URI for this resource.
    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).
    default boolean
    isStale(long lastLoadTimestamp)
    Checks if the source has changed since the last load timestamp.
    default boolean
    isTextual()
    Determines if the resource is textual and suitable for a TextView.
    boolean
    isVirtual()
    Determines if this is a virtual, memory-backed handle.
    default boolean
    isWritable()
    Determines if the resource is writable in the current environment.
    default long
    length()
    Returns the total length of the resource content in characters/bytes.
    InputStream
    openStream()
    Opens a fresh input stream to the resource content.
    void
    setOwner(Resource owner)
    Associates this handle with its parent Resource.
    default void
    write(String content)
    Agnostically writes text content back to the resource.

    Methods inherited from interface Rebindable

    rebind

  • Method Details

    • getUri

      URI getUri()
      Gets the unique URI for this resource.
      Returns:
      The identifier URI.

    • getName

      String getName()
      Returns a user-friendly name for the source.
      Returns:
      The source name.

    • getHtmlDisplayName

      default String 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

      InputStream openStream() throws IOException
      Opens a fresh input stream to the resource content.
      Returns:
      A new InputStream instance.
      Throws:
      IOException - if the stream cannot be opened.

    • asText

      default String asText() throws IOException
      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

      default byte[] asBytes() throws IOException
      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) operation.

    • write

      default void write(String content) throws IOException
      Agnostically writes text content back to the resource.

      Purity Note: Read-only handles should throw UnsupportedOperationException.

      Parameters:
      content - The text to write.
      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

      default Charset 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.

    • 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

      default String 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

      void setOwner(Resource owner)
      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.