Package org.apache.tika.pipes.core

Interface ServerManager

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
PerClientServerManager, SharedServerManager
public interface ServerManager extends Closeable
Manages the lifecycle of a PipesServer process and client connections.

Implementations handle starting, monitoring, and restarting the server process. In per-client mode (default), each PipesClient has its own ServerManager. In shared mode, multiple PipesClients share a single ServerManager.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Socket
    connect(int socketTimeoutMillis)
    Establishes a connection to the server and returns a connected Socket.
    default void
    connectionAbandoned()
    Signals that the client walked away from its connection, whether mid-handshake or with a request still in flight.
    void
    ensureRunning()
    Ensures the server is running, starting or restarting it if necessary.
    long
    getGeneration()
    The generation of the currently running process: a counter incremented every time this manager forks a replacement.
    int
    getPort()
    Returns the port number the server is listening on.
    default long
    getRestartCount(RestartReason reason)
    Restarts performed so far for reason; monotonic, never reset.
    Path
    getTempDirectory()
    Returns the path to the temporary directory used by the server.
    int
    handleCrashAndGetExitCode(long generation)
    Handles a crash by checking the process exit code and marking for restart.
    default void
    incrementFilesProcessed(long maxFilesPerProcess)
    Increments the count of files processed and marks for restart if limit reached.
    boolean
    isRunning()
    Checks if the server process is currently running.
    void
    markServerForRestart(RestartReason reason, long generation)
    Marks the server for restart due to a fatal error, attributed to reason, but only if generation is still current -- reports about a superseded process are dropped.
    default boolean
    needsRestart()
    Checks if the server has been marked for restart.
    void
    shutdown()
    Shuts down the server process and cleans up resources.

    Methods inherited from interface java.io.Closeable

    close

  • Method Details

    • getPort

      int getPort()
      Returns the port number the server is listening on. May return -1 if the server hasn't been started yet.
      Returns:
      the server port, or -1 if not started

    • ensureRunning

      void ensureRunning() throws IOException, InterruptedException, TimeoutException, ServerInitializationException
      Ensures the server is running, starting or restarting it if necessary.

      In shared mode, this method is synchronized to prevent multiple clients from attempting to restart the server simultaneously.

      Throws:
      IOException - if the server cannot be started
      InterruptedException - if interrupted while waiting for server startup
      TimeoutException - if the server doesn't start within the configured timeout
      ServerInitializationException - if the server fails to initialize

    • connect

      Socket connect(int socketTimeoutMillis) throws IOException, ServerInitializationException
      Establishes a connection to the server and returns a connected Socket.

      The behavior differs by implementation:

      • Per-client mode: Accepts incoming connection from the dedicated server
      • Shared mode: Connects out to the shared server

      This method should be called after ensureRunning().

      Parameters:
      socketTimeoutMillis - the socket timeout in milliseconds
      Returns:
      a connected Socket ready for communication
      Throws:
      IOException - if connection fails
      ServerInitializationException - if the server died before connecting

    • shutdown

      void shutdown() throws InterruptedException
      Shuts down the server process and cleans up resources. After calling this method, ensureRunning() can be called to restart.
      Throws:
      InterruptedException - if interrupted while waiting for shutdown

    • isRunning

      boolean isRunning()
      Checks if the server process is currently running.
      Returns:
      true if the server process is running

    • getTempDirectory

      Path getTempDirectory()
      Returns the path to the temporary directory used by the server. May return null if the server hasn't been started yet.
      Returns:
      the temp directory path, or null if not started

    • getGeneration

      long getGeneration()
      The generation of the currently running process: a counter incremented every time this manager forks a replacement. A client captures it when it connects and hands it back with every report, so a report about a process that has already been replaced can be recognised and dropped rather than being applied to its healthy successor.

    • markServerForRestart

      void markServerForRestart(RestartReason reason, long generation)
      Marks the server for restart due to a fatal error, attributed to reason, but only if generation is still current -- reports about a superseded process are dropped.

      Called by a client that received a fatal status: the process is stopping even if isRunning() still says otherwise, and the next ensureRunning() waits for it to exit and restarts it.

      Deliberately the only spelling, and deliberately abstract. Earlier revisions offered a no-arg and a reasonless form defaulting to one another; an implementation that overrode only one left the others silently inert, which is how a worker known to be poisoned kept being handed documents.

    • getRestartCount

      default long getRestartCount(RestartReason reason)
      Restarts performed so far for reason; monotonic, never reset.

    • connectionAbandoned

      default void connectionAbandoned()
      Signals that the client walked away from its connection, whether mid-handshake or with a request still in flight.

      A per-client worker dials the parent once and never dials back, so an abandoned worker must be recycled or the next connect(int) waits out the full accept timeout against a process that will never call. A shared server outlives its clients and needs nothing here; its connection handlers already detect the dead socket themselves.

    • incrementFilesProcessed

      default void incrementFilesProcessed(long maxFilesPerProcess)
      Increments the count of files processed and marks for restart if limit reached.

      This tracks progress toward the maxFilesProcessedPerProcess limit. When the limit is reached, needsRestart() will return true and the next call to ensureRunning() will restart the server.

      Parameters:
      maxFilesPerProcess - the maximum files before restart (0 means unlimited)

    • needsRestart

      default boolean needsRestart()
      Checks if the server has been marked for restart.

      This allows clients to detect that a restart is pending before attempting to use an existing connection that might be stale.

      Returns:
      true if the server has been marked for restart

    • handleCrashAndGetExitCode

      int handleCrashAndGetExitCode(long generation)
      Handles a crash by checking the process exit code and marking for restart.

      In per-client mode, waits briefly for the process to exit and checks the exit code to determine if this was an OOM or TIMEOUT. In shared mode, just marks for restart (exit code checking is not reliable since multiple clients share the process).

      Returns:
      the exit code if available, or -1 if the process is still running or unavailable