org.apache.tinkerpop.gremlin.server

## Class Settings

- java.lang.Object
- - org.apache.tinkerpop.gremlin.server.Settings

-     public class Settings
      extends Object

  Server settings as configured by a YAML file.
  Author:
    Stephen Mallette (http://stephen.genoprime.com)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Settings.AuthenticationSettings` Settings for the `Authenticator` implementation.
    `static class` | `Settings.AuthorizationSettings` Settings for the `Authenticator` implementation.
    `static class` | `Settings.BaseMetrics`
    `static class` | `Settings.ConsoleReporterMetrics` Settings for a `Metrics` reporter that writes to the console.
    `static class` | `Settings.CsvReporterMetrics` Settings for a `Metrics` reporter that writes to a CSV file.
    `static class` | `Settings.GangliaReporterMetrics` Settings for a `Metrics` reporter that writes to Ganglia.
    `static class` | `Settings.GraphiteReporterMetrics` Settings for a `Metrics` reporter that writes to Graphite.
    `static class` | `Settings.HostPortIntervalMetrics`
    `static class` | `Settings.IntervalMetrics`
    `static class` | `Settings.JmxReporterMetrics` Settings for a `Metrics` reporter that writes to JMX.
    `static class` | `Settings.ProcessorSettings` Custom configurations for any `OpProcessor` implementations.
    `static class` | `Settings.ScriptEngineSettings` Settings for the `ScriptEngine`.
    `static class` | `Settings.SerializerSettings` Settings for the `MessageSerializer` implementations.
    `static class` | `Settings.ServerMetrics` Settings for `Metrics` recorded by Gremlin Server.
    `static class` | `Settings.Slf4jReporterMetrics` Settings for a `Metrics` reporter that writes to the SL4J output.
    `static class` | `Settings.SslSettings` Settings to configure SSL support.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `Settings.AuthenticationSettings` | `authentication`
    `Settings.AuthorizationSettings` | `authorization`
    `String` | `channelizer` The full class name of the `Channelizer` to use in Gremlin Server.
    `Boolean` | `enableAuditLog` Enable audit logging of authenticated users and gremlin evaluation requests.
    `long` | `evaluationTimeout` Time in milliseconds to wait for a request (script or bytecode) to complete execution.
    `String` | `graphManager` The full class name of the `GraphManager` to use in Gremlin Server.
    `Map<String,String>` | `graphs` `Map` of `Graph` objects keyed by their binding name.
    `int` | `gremlinPool` Size of the Gremlin thread pool.
    `String` | `host` Host to bind the server to.
    `long` | `idleConnectionTimeout` Time in milliseconds that the server will allow a channel to not receive requests from a client before it automatically closes.
    `long` | `keepAliveInterval` Time in milliseconds that the server will allow a channel to not send responses to a client before it sends a "ping" to see if it is still present.
    `int` | `maxAccumulationBufferComponents` Maximum number of request components that can be aggregated for a message.
    `int` | `maxChunkSize` The maximum length of the content or each chunk.
    `int` | `maxContentLength` The maximum length of the aggregated content for a message.
    `int` | `maxHeaderSize` The maximum length of all headers.
    `int` | `maxInitialLineLength` The maximum length of the initial line (e.g.
    `int` | `maxParameters` Maximum number of parameters that can be passed on a request.
    `int` | `maxSessionTaskQueueSize` Maximum size that an individual `Session` can queue requests before starting to reject them.
    `int` | `maxWorkQueueSize` Maximum size the general processing queue can grow before starting to reject requests.
    `Settings.ServerMetrics` | `metrics` Configured metrics for Gremlin Server.
    `int` | `port` Port to bind the server to.
    `List<Settings.ProcessorSettings>` | `processors` Custom settings for `OpProcessor` implementations.
    `int` | `resultIterationBatchSize` Number of items in a particular resultset to iterate and serialize prior to pushing the data down the wire to the client.
    `Map<String,Settings.ScriptEngineSettings>` | `scriptEngines` `Map` of settings for `ScriptEngine` setting objects keyed by the name of the `ScriptEngine` implementation.
    `List<Settings.SerializerSettings>` | `serializers` List of `MessageSerializer` to configure.
    `long` | `sessionLifetimeTimeout` The time in milliseconds that a `UnifiedChannelizer` session can exist.
    `Settings.SslSettings` | `ssl` Configures settings for SSL.
    `boolean` | `strictTransactionManagement` If set to `true` the `aliases` option is required on requests and Gremlin Server will use that information to control which `Graph` instances are transaction managed for that request.
    `int` | `threadPoolBoss` Size of the boss thread pool.
    `int` | `threadPoolWorker` Size of the worker thread pool.
    `boolean` | `useCommonEngineForSessions` When `true` and using the `UnifiedChannelizer` the same engine that will be used to server sessionless requests will also be use to serve sessions.
    `boolean` | `useEpollEventLoop` detect if the OS is linux, then use epoll instead of NIO which causes less GC
    `boolean` | `useGlobalFunctionCacheForSessions` Enable the global function cache for sessions when using the `UnifiedChannelizer`.
    `int` | `writeBufferHighWaterMark` If the number of bytes in the network send buffer exceeds this value then the channel is no longer writeable, accepting no additional writes until buffer is drained and the `writeBufferLowWaterMark` is met.
    `int` | `writeBufferLowWaterMark` Once the number of bytes queued in the network send buffer exceeds the high water mark, the channel will not become writeable again until the buffer is drained and it drops below this value.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Settings()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static org.yaml.snakeyaml.constructor.Constructor` | `createDefaultYamlConstructor()` Creates `Constructor` which contains all configurations to parse a Gremlin Server YAML configuration file using SnakeYAML.
    `long` | `getEvaluationTimeout()`
    `Optional<Settings.ServerMetrics>` | `optionalMetrics()`
    `Optional<Settings.ProcessorSettings>` | `optionalProcessor(Class<? extends OpProcessor> clazz)` Find the `Settings.ProcessorSettings` related to the specified class.
    `Optional<Settings.SslSettings>` | `optionalSsl()`
    `static Settings` | `read(InputStream stream)` Read configuration from a file into a new `Settings` object.
    `static Settings` | `read(String file)` Read configuration from a file into a new `Settings` object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### host

          public String host

      Host to bind the server to. Defaults to localhost.

    - #### port

          public int port

      Port to bind the server to. Defaults to 8182.

    - #### threadPoolWorker

          public int threadPoolWorker

      Size of the worker thread pool. Defaults to 1 and should generally not exceed 2 * number of cores. A worker thread performs non-blocking read and write for one or more Channels in a non-blocking mode.

    - #### useEpollEventLoop

          public boolean useEpollEventLoop

      detect if the OS is linux, then use epoll instead of NIO which causes less GC

    - #### gremlinPool

          public int gremlinPool

      Size of the Gremlin thread pool. This pool handles Gremlin script execution and other related "long-run" processing. Defaults to a setting of 0 which indicates the value should be set to `Runtime#availableProcessors()`.

    - #### threadPoolBoss

          public int threadPoolBoss

      Size of the boss thread pool. Defaults to 1 and should likely stay at 1. The bossy thread accepts incoming connections on a port until it is unbound. Once a connection is accepted successfully, the boss thread passes processing to the worker threads.

    - #### evaluationTimeout

          public long evaluationTimeout

      Time in milliseconds to wait for a request (script or bytecode) to complete execution. Defaults to 30000.

    - #### resultIterationBatchSize

          public int resultIterationBatchSize

      Number of items in a particular resultset to iterate and serialize prior to pushing the data down the wire to the client.

    - #### maxInitialLineLength

          public int maxInitialLineLength

      The maximum length of the initial line (e.g. `"GET / HTTP/1.0"`) processed in a request, which essentially controls the maximum length of the submitted URI. This setting ties to the Netty `HttpRequestDecoder`.

    - #### maxHeaderSize

          public int maxHeaderSize

      The maximum length of all headers. This setting ties to the Netty `HttpRequestDecoder`

    - #### maxChunkSize

          public int maxChunkSize

      The maximum length of the content or each chunk. If the content length exceeds this value, the transfer encoding of the decoded request will be converted to 'chunked' and the content will be split into multiple `HttpContent`s. If the transfer encoding of the HTTP request is 'chunked' already, each chunk will be split into smaller chunks if the length of the chunk exceeds this value.

    - #### maxContentLength

          public int maxContentLength

      The maximum length of the aggregated content for a message. Works in concert with `maxChunkSize` where chunked requests are accumulated back into a single message. A request exceeding this size will return a 413 - Request Entity Too Large status code. A response exceeding this size will raise an internal exception.

    - #### maxAccumulationBufferComponents

          public int maxAccumulationBufferComponents

      Maximum number of request components that can be aggregated for a message.

    - #### writeBufferHighWaterMark

          public int writeBufferHighWaterMark

      If the number of bytes in the network send buffer exceeds this value then the channel is no longer writeable, accepting no additional writes until buffer is drained and the `writeBufferLowWaterMark` is met.

    - #### writeBufferLowWaterMark

          public int writeBufferLowWaterMark

      Once the number of bytes queued in the network send buffer exceeds the high water mark, the channel will not become writeable again until the buffer is drained and it drops below this value.

    - #### idleConnectionTimeout

          public long idleConnectionTimeout

      Time in milliseconds that the server will allow a channel to not receive requests from a client before it automatically closes. If enabled, the value provided should typically exceed the amount of time given to `keepAliveInterval`. Note that while this value is to be provided as milliseconds it will resolve to second precision. Set this value to 0 to disable this feature.

    - #### keepAliveInterval

          public long keepAliveInterval

      Time in milliseconds that the server will allow a channel to not send responses to a client before it sends a "ping" to see if it is still present. If it is present, the client should respond with a "pong" which will thus reset the `idleConnectionTimeout` and keep the channel open. If enabled, this number should be smaller than the value provided to the `idleConnectionTimeout`. Note that while this value is to be provided as milliseconds it will resolve to second precision. Set this value to 0 to disable this feature.

    - #### strictTransactionManagement

          public boolean strictTransactionManagement

      If set to `true` the `aliases` option is required on requests and Gremlin Server will use that information to control which `Graph` instances are transaction managed for that request. If this setting is false (which is the default), specification of `aliases` is not required and Gremlin Server will simply apply a commit for all graphs. This setting only applies to sessionless requests. With either setting the user is responsible for their own transaction management for in-session requests.

    - #### channelizer

          public String channelizer

      The full class name of the `Channelizer` to use in Gremlin Server.

    - #### graphManager

          public String graphManager

      The full class name of the `GraphManager` to use in Gremlin Server.

    - #### maxWorkQueueSize

          public int maxWorkQueueSize

      Maximum size the general processing queue can grow before starting to reject requests. The general processing queue is managed by a thread pool that has its size determined by `gremlinPool`. All incoming requests will be processed by this thread pool. If the threads are exhausted, the requests will queue to the size specified by this value after which they will begin to reject the requests.

      This value should be taken in account with the `maxSessionTaskQueueSize` which is related in some respects. A request that starts a new `Session` is handled by this queue, but additional requests to a created `Session` will queue separately given that setting per session.

      By default this value is set to 8192.

    - #### maxSessionTaskQueueSize

          public int maxSessionTaskQueueSize

      Maximum size that an individual `Session` can queue requests before starting to reject them. Note that this configuration only applies to the `UnifiedChannelizer`. By default this value is set to 4096.
      See Also:
        `maxWorkQueueSize`

    - #### maxParameters

          public int maxParameters

      Maximum number of parameters that can be passed on a request. Larger numbers may impact performance for scripts. The default is 16 and this setting only applies to the `UnifiedChannelizer`.

    - #### sessionLifetimeTimeout

          public long sessionLifetimeTimeout

      The time in milliseconds that a `UnifiedChannelizer` session can exist. This value cannot be extended beyond this value irrespective of the number of requests and their individual timeouts. Requests must complete within this time frame. If this timeout is reached while there is a running evaluation, there will be an attempt to interrupt it which will result in a timeout error to the client. If there are existing requests enqueued for the session when this timeout is reached, those requests will not be executed and will be closed with server errors. Open transactions will be issued a rollback. The default is 10 minutes.

    - #### useGlobalFunctionCacheForSessions

          public boolean useGlobalFunctionCacheForSessions

      Enable the global function cache for sessions when using the `UnifiedChannelizer`. This setting is only relevant when `useGlobalFunctionCacheForSessions` is `false`. When `true` it means that functions created in one request to a session remain available on the next request to that session.

    - #### useCommonEngineForSessions

          public boolean useCommonEngineForSessions

      When `true` and using the `UnifiedChannelizer` the same engine that will be used to server sessionless requests will also be use to serve sessions. The default value of `true` is recommended as it reduces the amount of object creation required for each session and should generally lead to better performance especially if the expectation is that there will be many sessions being created and destroyed rapidly. Setting this value to `false` is mostly present to support specific use cases that may require each session having its own engine or to match previous functionality provided by the older channelizers produced prior to 3.5.0.

    - #### metrics

          public Settings.ServerMetrics metrics

      Configured metrics for Gremlin Server.

    - #### graphs

          public Map<String,String> graphs

      `Map` of `Graph` objects keyed by their binding name.

    - #### scriptEngines

          public Map<String,Settings.ScriptEngineSettings> scriptEngines

      `Map` of settings for `ScriptEngine` setting objects keyed by the name of the `ScriptEngine` implementation.

    - #### serializers

          public List<Settings.SerializerSettings> serializers

      List of `MessageSerializer` to configure. If no serializers are specified then default serializers for the most current versions of "application/json" and "application/vnd.gremlin-v1.0+gryo" are applied.

    - #### ssl

          public Settings.SslSettings ssl

      Configures settings for SSL.

    - #### authentication

          public Settings.AuthenticationSettings authentication

    - #### authorization

          public Settings.AuthorizationSettings authorization

    - #### enableAuditLog

          public Boolean enableAuditLog

      Enable audit logging of authenticated users and gremlin evaluation requests.

    - #### processors

          public List<Settings.ProcessorSettings> processors

      Custom settings for `OpProcessor` implementations. Implementations are loaded via `ServiceLoader` but custom configurations can be supplied through this configuration.

  - ### Constructor Detail

    - #### Settings

          public Settings()

  - ### Method Detail

    - #### optionalProcessor

          public Optional<Settings.ProcessorSettings> optionalProcessor(Class<? extends OpProcessor> clazz)

      Find the `Settings.ProcessorSettings` related to the specified class. If there are multiple entries then only the first is returned.

    - #### optionalMetrics

          public Optional<Settings.ServerMetrics> optionalMetrics()

    - #### optionalSsl

          public Optional<Settings.SslSettings> optionalSsl()

    - #### getEvaluationTimeout

          public long getEvaluationTimeout()

    - #### read

          public static Settings read(String file)
                               throws Exception

      Read configuration from a file into a new `Settings` object.
      Parameters:
        `file` - the location of a Gremlin Server YAML configuration file
      Returns:
        a new `Optional` object wrapping the created `Settings`
      Throws:
        `Exception`

    - #### createDefaultYamlConstructor

          protected static org.yaml.snakeyaml.constructor.Constructor createDefaultYamlConstructor()

      Creates `Constructor` which contains all configurations to parse a Gremlin Server YAML configuration file using SnakeYAML.
      Returns:
        a `Constructor` to parse a Gremlin Server YAML

    - #### read

          public static Settings read(InputStream stream)

      Read configuration from a file into a new `Settings` object.
      Parameters:
        `stream` - an input stream containing a Gremlin Server YAML configuration
      Returns:
        a new `Optional` object wrapping the created `Settings`

Copyright © 2013–2022 Apache Software Foundation. All rights reserved.