Package limn.transfer

Class DataFormat<T>

java.lang.Object
limn.transfer.DataFormat<T>
Type Parameters:
T - the type of the value this format carries
public final class DataFormat<T> extends Object
One representation of what is copied or dragged, and the Java type that holds it.

Four formats are the ones every desktop program exchanges: TEXT, HTML, IMAGE and FILES. An application adds its own in two ways. of(java.lang.String, java.util.function.Function<T, byte[]>, java.util.function.Function<byte[], T>) names a format and says how its value becomes bytes, so it can cross to another program, or to another run of this one. inProcess carries the object itself and never leaves this process: what a list hands another list of the same window.

Two formats are equal when their names are. Declare each once, in a constant.

  • Field Details

    • TEXT

      public static final DataFormat<String> TEXT
      Plain text.

    • HTML

      public static final DataFormat<String> HTML
      A fragment of HTML, as a word processor or a spreadsheet pastes it with its formatting.

    • IMAGE

      public static final DataFormat<Image> IMAGE
      A picture.

    • FILES

      public static final DataFormat<List<Path>> FILES
      Files and directories, as a file manager copies and drags them.

  • Method Details

    • of

      public static <T> DataFormat<T> of(String name, Function<T,byte[]> encode, Function<byte[],T> decode)
      Declares a format of the application's own, carried as bytes under a name another program can ask for too. From this call on, something offered under that name by anyone is listed by Offer.formats() as this format.

      The name is written as a media type, application/x-acme-order: lower case, one slash, no spaces. It is the type the Linux desktops see as written, a registered clipboard format on Windows and a pasteboard type on macOS. Declaring a name again replaces the earlier declaration.

      Type Parameters:
      T - the type of the value
      Parameters:
      name - the format's name
      encode - the value as bytes
      decode - the bytes as a value; what it throws fails the read
      Returns:
      the format
      Throws:
      IllegalArgumentException - if the name is not a media type, or is one of the four standard formats'

    • inProcess

      public static <T> DataFormat<T> inProcess(String name, Class<T> type)
      Declares a format that carries the object itself. It costs no encoding, it is offered to this process alone, and it is gone when the process ends: another program, and another run of this one, never see it.
      Type Parameters:
      T - the type of the value
      Parameters:
      name - the format's name, written as of(java.lang.String, java.util.function.Function<T, byte[]>, java.util.function.Function<byte[], T>) asks
      type - the class of the value, which a read is checked against
      Returns:
      the format
      Throws:
      IllegalArgumentException - if the name is not a media type, or is one of the four standard formats'

    • declared

      public static @Nullable DataFormat<?> declared(String name)
      The format an application declared under a name with of(java.lang.String, java.util.function.Function<T, byte[]>, java.util.function.Function<byte[], T>), for a backend that finds the name among what a platform offers.
      Parameters:
      name - a native type's name
      Returns:
      the declared format, or null when the application declared none by that name

    • name

      public String name()
      Returns:
      the format's name: a media type

    • isStandard

      public boolean isStandard()
      Returns:
      whether this is one of TEXT, HTML, IMAGE, FILES

    • isInProcess

      public boolean isInProcess()
      Returns:
      whether the value is carried as the object itself, within this process only

    • encode

      public byte[] encode(T value)
      The value as the bytes another program is handed; for a backend.
      Parameters:
      value - the value
      Returns:
      its bytes
      Throws:
      UnsupportedOperationException - for a standard or an in-process format, whose bytes are the platform's business or do not exist

    • decode

      public T decode(byte[] bytes)
      The bytes another program handed over as a value; for a backend.
      Parameters:
      bytes - the bytes
      Returns:
      the value
      Throws:
      UnsupportedOperationException - for a standard or an in-process format

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object