Interface DocProperty<E>

Type Parameters:
E - the type which gets read/written by this property.
All Known Implementing Classes:
DefaultingDocProperty, ReadOnlyDocProperty, RewritingDocProperty, StandardDocProperty
public interface DocProperty<E>
Represents a property which can be written and read from a Document or DocPropertyHolder, for example the amount of online players, the state of the service or other custom properties appended by a plugin. This simplifies accessing these properties by making a common wrapper once.

The old code might look like this: 

 
  public final class GameListener implement Listener {
    public void handleJoin(PlayerLoginEvent event) {
      ServiceInfoSnapshot snapshot = this.manager.currentSnapshot();
      GameState state = snapshot.propertyHolder().get("state", GameState.class);

      if (state == GameState.STARTED) {
        event.setResult(PlayerLoginEvent.Result.DENIED);
      }
    }
  }

All the property read code can now be replaced by a simple static field like this: 

 
  public final class GameListener implement Listener {
    public static final DocProperty<GameState> STATE =
      DocProperty.property("state", GameState.class);

    public void handleJoin(PlayerLoginEvent event) {
      // a service snapshot is a property holder
      DocPropertyHolder propertyHolder = this.manager.currentSnapshot();
      GameState state = propertyHolder.readProperty(STATE);

      if (state == GameState.STARTED) {
        event.setResult(PlayerLoginEvent.Result.DENIED);
      }
    }
  }
Since:
4.0

  • Method Details

    • property

      @NonNull static <E> @NonNull DocProperty<E> property(@NonNull @NonNull String key, @NonNull @NonNull Class<E> type)
      Creates a new property that reads and writes values of the given type from/into a document using the given key.
      Type Parameters:
      E - the type of member that is processed by the doc property.
      Parameters:
      key - the key that is used when the member is written to/read from the underlying document.
      type - the type of the member that gets wrapped by the property.
      Returns:
      a doc property that can read/write members with the given key and type from a document.
      Throws:
      NullPointerException - if the given key or type is null.

    • genericProperty

      @NonNull static <E> @NonNull DocProperty<E> genericProperty(@NonNull @NonNull String key, @NonNull @NonNull Type type)
      Creates a new property that reads and writes values of the given type from/into a document using the given key.
      Type Parameters:
      E - the type of member that is processed by the doc property.
      Parameters:
      key - the key that is used when the member is written to/read from the underlying document.
      type - the type of the member that gets wrapped by the property.
      Returns:
      a doc property that can read/write members with the given key and type from a document.
      Throws:
      NullPointerException - if the given key or type is null.

    • key

      @NonNull @NonNull String key()
      Get the key of the member that is read from/written to a document.
      Returns:
      the key of the member that is read from/written to a document.

    • readOnly

      boolean readOnly()
      Get if this property only supports being read from a document but not being written to one.
      Returns:
      true if this property is read-only, false otherwise.

    • asReadOnly

      @CheckReturnValue @NonNull @NonNull DocProperty<E> asReadOnly()
      Wraps this property in a new property that makes any write operation with this property throw an exception. Read operations will be delegated to the property this method is being called on.

      If this property is already read-only the current property is returned without wrapping.

      Returns:
      a property that wraps this property to make it read-only.

    • withDefault

      @CheckReturnValue @NonNull @NonNull DocProperty<E> withDefault(@Nullable E def)
      Wraps this property to make read and write operations set a default value in case the given value is either absent (not appended to the document) or set to null. Read and write operations are delegated to the property this method is being called on.

      If this property already has a default and the given default is the same as current one (as defined by ==) the current property is returned without wrapping.

      Parameters:
      def - the default value to use for the property.
      Returns:
      a property that wraps this property and sets a default value during read and write operations.

    • withReadRewrite

      @CheckReturnValue @NonNull <V> @NonNull DocProperty<V> withReadRewrite(@NonNull @NonNull Function<E,V> rewriteFunction)
      Wraps this property to apply a rewrite function when reading the property from a document. The parsed type of this property is passed to the function and returned as the new property value. Null values are not passed to the function and returned without processing.

      Note: as this method only sets a function to rewrite while reading the value, the returned property will be read-only as values passed for writing cannot be converted. Use withReadWriteRewrite(Function, Function) to set a function that is called during writing as well.

      Type Parameters:
      V - the type of value that is the result of the value convert process.
      Parameters:
      rewriteFunction - the rewrite function to call when reading the value from a document.
      Returns:
      a read-only property that wraps this property and applies the given rewrite function when reading.
      Throws:
      NullPointerException - if the given rewrite function is null.

    • withReadWriteRewrite

      @CheckReturnValue @NonNull <V> @NonNull DocProperty<V> withReadWriteRewrite(@NonNull @NonNull Function<E,V> readRewriteFunction, @Nullable @Nullable Function<V,E> writeRewriteFunction)
      Wraps this property to apply a rewrite function when reading and writing the property from/to a document. The parsed type of this property is passed to the function and returned/written as the new property value. Null values are not passed to the function and returned without processing.

      Note: if the call to this method only sets a function to rewrite while reading the value (setting the rewrite function for reads to null), the returned property will be read-only as values passed for writing cannot be converted.

      Type Parameters:
      V - the type of value that is the result of the value convert process.
      Parameters:
      readRewriteFunction - the rewrite function to call when reading the value from a document.
      writeRewriteFunction - the rewrite function to call when writing the value to a document, can be null.
      Returns:
      a property that wraps this property and applies the given rewrite function when reading or writing.
      Throws:
      NullPointerException - if the given read rewrite function is null.

    • readFrom

      @Nullable E readFrom(@NonNull @NonNull Document document)
      Called to read the value of this property from the given document.
      Parameters:
      document - the document to read the value from.
      Returns:
      the parsed value from the document, or null if the value is not present.
      Throws:
      NullPointerException - if the given document is null.

    • writeTo

      @NonNull @NonNull DocProperty<E> writeTo(@NonNull Document.Mutable document, @Nullable E value)
      Writes the given value into the given document.
      Parameters:
      document - the document to write the value to.
      value - the value to write.
      Returns:
      the same property as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given document is null.
      UnsupportedOperationException - if this property does not support writing values to a document.