Interface DocumentViewBuilder

public interface DocumentViewBuilder
An interface for building a document view.

When creating a document view, if more than 1 player is specified, then it's required that setSpawnLocation(Location) also be set explicitly.
This is because the system for automatically determining for where to spawn a page only works if there's exactly 1 player in the getPlayers() player set.
If it's empty, then it doesn't know where to spawn, if there's more than 1, then it's not possible to know which player it should be spawned in front of, as the players may be in different locations and different worlds on the server.

  • Method Details

    • getPath

      @Nullable @Nullable ResourcePath getPath()
      Get the path the request will be sent to
      Returns:
      Request path

    • setPath

      DocumentViewBuilder setPath(@NotNull @NotNull ResourcePath path)
      Set the resource path the document will be fetched from.
      Parameters:
      path - Document resource path
      Returns:
      this
      Throws:
      NullPointerException - If path is null

    • setPath

      DocumentViewBuilder setPath(@NotNull @NotNull String path) throws DelphiException
      Set the resource path the document will be fetched from.

      Shorthand for calling setPath(ResourcePath) and Delphi.parsePath(String)

      Parameters:
      path - Document resource path
      Returns:
      this
      Throws:
      NullPointerException - If path is null.
      DelphiException - (With Error code DelphiException.ERR_INVALID_PATH) If the path cannot be parsed.

    • getInstanceName

      @Nullable @Nullable String getInstanceName()
      Get the currently set instance name.

      Instance names are unique names given to each page used to differentiate them from other open pages of the same module or same resource path.

      Returns:
      Instance name

    • setInstanceName

      DocumentViewBuilder setInstanceName(@Nullable @Nullable String instanceName)
      Set the instance name of the view.

      Instance names are unique names given to each page used to differentiate them from other open pages of the same module or same resource path.

      Parameters:
      instanceName - New instance name
      Returns:
      this

    • getPlayers

      PlayerSet getPlayers()
      Get the player the opened document will be linked to.

      Unless any of the player set methods have been called, this will return a set of all online players.

      Returns:
      Request player.

    • setPlayer

      DocumentViewBuilder setPlayer(@NotNull @NotNull org.bukkit.entity.Player player)
      Set the player the opened document will be linked to.

      If there are any other players in the getPlayers() set, then they will be removed and only the specified player will be in that set.

      Parameters:
      player - player
      Returns:
      this
      Throws:
      NullPointerException - If player is null

    • setPlayers

      DocumentViewBuilder setPlayers(@NotNull @NotNull Collection<org.bukkit.entity.Player> players)
      Set the players that resulting view will be visible and interactable to.
      Parameters:
      players - Player collection
      Returns:
      this
      Throws:
      NullPointerException - If players, or any element in players is null

    • addPlayers

      DocumentViewBuilder addPlayers(@NotNull @NotNull Collection<org.bukkit.entity.Player> players)
      Add players that resulting view will be visible and interactable to.

      If allPlayers() has been called before this, then this acts identically to setPlayers(Collection).

      Parameters:
      players - Player collection
      Returns:
      this
      Throws:
      NullPointerException - If players, or any element in players is null

    • addPlayer

      DocumentViewBuilder addPlayer(@NotNull @NotNull org.bukkit.entity.Player player)
      Add a player to the resulting view.

      Adding a player to the view means the player can see and use the document page.

      If allPlayers() has been called, this method acts identically to setPlayer(Player).

      Parameters:
      player - Player
      Returns:
      this
      Throws:
      NullPointerException - If player is null
      See Also:

    • allPlayers

      DocumentViewBuilder allPlayers()
      Make the resulting view visible to all online players.

      This means the resulting view will be shown to all players and can be used by all players.

      Returns:
      this

    • getSpawnLocation

      @Nullable @Nullable org.bukkit.Location getSpawnLocation()
      Get the set spawn location for the opened document.

      If this is not set, the document will be spawned in front of the player, facing the player.

      Returns:
      Document spawn location

    • setSpawnLocation

      DocumentViewBuilder setSpawnLocation(@Nullable @Nullable org.bukkit.Location location)
      Set the spawn location of the opened document.

      If set to null, then the document will be spawned in front of the player, facing the player.

      Parameters:
      location - Spawn location
      Returns:
      this

    • open

      Result<DocumentView, DelphiException> open() throws NullPointerException, IllegalStateException
      Attempts to open the document specified by getPath() and show it to the getPlayers().

      Uses DelphiResources.findModule(String) to find the module of the getPath(), then creates a ViewResources object with the module and attempts to call ViewResources.loadDocument(String) with the path given to this method.

      If the document is successfully loaded and initialized, it is spawned and then shown to the players, and the created document view is returned.

      Any erroneous result returned by this method will have an error code dictated by either the DelphiResources.findModule(String) or ViewResources.loadDocument(String) methods.

      Special error codes
      Error code Description
      ERR_INSTANCE_NAME_USED The specified getInstanceName() is already in use
      ERR_ILLEGAL_INSTANCE_NAME The specified getInstanceName() is not allowed
      Most likely because its usage would interfere with a command.
      Returns:
      The opened view, or an error result explaining why the document couldn't be opened.
      Throws:
      NullPointerException - If getPath() is unset
      IllegalStateException - If getPlayers() does not contain exactly 1 player, and no getSpawnLocation() has been set.
      This means if the player set is empty, or contains more than 1 player, the system cannot figure out where to spawn the page by itself, and requires a spawn location to be set.

    • openOrThrow

      DocumentView openOrThrow() throws NullPointerException, IllegalStateException
      Invokes open() and if an erroneous result is returned, the exception is thrown.
      Returns:
      Opened document view.
      Throws:
      DelphiException - If the document failed to be opened for any reason
      NullPointerException - If getPath() is unset
      IllegalStateException - If getPlayers() does not contain exactly 1 player, and no getSpawnLocation() has been set.
      This means if the player set is empty, or contains more than 1 player, the system cannot figure out where to spawn the page by itself, and requires a spawn location to be set.

    • openOrLog

      Optional<DocumentView> openOrLog() throws NullPointerException, IllegalStateException
      Invokes open() and if an erroneous result is returned, it is logged and an empty optional returned. If the open() invocation succeeds, an optional containing the opened view is returned.
      Returns:
      View optional
      Throws:
      NullPointerException - If getPath() is unset
      IllegalStateException - If getPlayers() does not contain exactly 1 player, and no getSpawnLocation() has been set.
      This means if the player set is empty, or contains more than 1 player, the system cannot figure out where to spawn the page by itself, and requires a spawn location to be set.