Spring Boot Sophora Commons

Common project to configure a connection to a Sophora Server

Spring Boot Sophora Commons is a convenient way to configure the connection to a Sophora Server in a Spring Boot project. Additional functionalty includes a health indicator for the server connection and metrics for the document cache.


First, add the following dependency to yourĀ pom.xml:


Then, you need to configure your project's @SpringBootApplication component scan to include the packageĀ com.subshell.sophora.springbootsophoracommons. Don't forget to add your project's package to the list, otherwise Spring won't scan it:

  scanBasePackages = {"<package of current project>", "com.subshell.sophora.springbootsophoracommons"}
public class MySpringBootApplication {
  // ...

Configuration of the Server Connection

Common configuration properties to connect to a Sophora Server

sophora.client.server-connection.urlsDefines the connection url to the Sophora Server. It is also possible to define a list of connection urls. This is especially useful in conjunction with the property sophora.client.server-connection.noOtherHosts.-
sophora.client.server-connection.urlThis configuration option is deprecated and will be removed from version 5. Please use sophora.client.server-connection.urls instead
sophora.client.server-connection.usernameSophora username-
sophora.client.server-connection.passwordThe password of the Sophora user-
sophora.client.server-connection.accessTokenDefines an accesstoken for a sessionless connection. Please refer the Sophora Cloud Delivery documentation for further information.-
sophora.client.server-connection.sessionlessDefines whether it is a sessionless connection or not. Please refer the Sophora Cloud Delivery documentation for further information.false
sophora.client.server-connection.noOtherHostsDefines whether a connection to another known server should be tried if the defined Sophroa Server is not reachable. If the value is set to true, an attempt is made to reach one of the configured servers.false
sophora.client.server-connection.deferLoginWhether the client should login in automatically. If set to true, the method com.subshell.sophora.client.ISophoraClient#login() must be called manuelly.false
sophora.client.server-connection.retriesSpecifies the number of connection retries the Sophora Client will attempt, when connecting to the server fails.3
sophora.client.server-connection.retryIntervalSpecifies the interval in seconds between connection retries to the server.5
sophora.client.server-connection.reconnectOnNonMatchingAPIIf set to false this client will not reconnect to the Sophora server if the API versions of the server and client are potentially incompatible.true
sophora.client.server-connection.useMigrationModeThe use of the migration mode is discouraged and should at most be used in migration scenarios.false
sophora.client.server-connection.internalEnforces the use of the internal connection data. By default the external connection data are used, if available. Please refer the configuration properties sophora.remote.api.external.* of the Sophora Server for further information about the external connection data.false
sophora.client.server-connection.readTimeoutSets the request timeout when communicating with the server in milliseconds. Use this setting if you are experiencing read timeouts.300000 (5 minutes)

Proxy Configuration

Configuration of a proxy that is used to connect to the Sophora Server

sophora.client.proxy.hostHostname of the proxy-
sophora.client.proxy.portPort of the proxy-
sophora.client.proxy.usernameUsername for authentication to the proxy-
sophora.client.proxy.passwordPassword for the username-
sophora.client.proxy.socksHostDefines the host of a Socks proxy-
sophora.client.proxy.socksPortDefines the port of a Socks proxy-

Cache Configuration

sophora.client.cache.cacheDirAbsolute path to the cache directory. Can be used to define the directory
in which the document cache will store its data. Will use an EhCache to cache the data per default. Should not be used if multiple SophoraClients will run in the same JVM. This has no effect if any of the documentCacheElementsInMemory options has been activated as these will result in a different cache implementation.
sophora.client.cache.thumbnailCacheSizeThe total number of thumbnails cached by this client..100
sophora.client.cache.documentCacheElementsInMemoryThe number of documents to be cached in memory.50
sophora.client.cache.publishedDocumentCacheElementsInMemoryThe number of published documents to be cached.50
sophora.client.cache.useDocumentCacheOverflowToDiskDefines whether the cache should be persisted on disk.false
sophora.client.cache.fireDocumentChangedEventForInheritedPropertiesChangesDefines whether DocumentChangedEvents should be broadcasted for changes of inherited properties.false

Binary Data

sophora.client.binary-data.binaryDataCacheMimeTypeBlacklistPer default, all binary data is cached. Specifies a list of mime types that should not be cached by the client.-
sophora.client.binary-data.binaryDataCacheMaximumSizeInBytesSets the maximum in-memory size of the overall binary data cache (not per entry) in bytes.128000000


Summarizes various configuration options

sophora.client.misc.dataDirAbsolute path to the data directory of the Sophora Info Dao.-
sophora.client.misc.localeSets the locale of the SophoraClient. Uses the ISO 639 alpha-2 or alpha-3 language
sophora.client.misc.jmxNameConfigures the name with which the SophoraClient will be presented via JMX.-
sophora.client.misc.updateIntervalSets the update interval in milliseconds in which the client will fetch events from the Sophora server.3000
sophora.client.misc.forceSlaveConnectionWhen true this client can log in to replica servers without being redirected to the primary server. When used to modify documents this will lead to differences between the Sophora servers that will not be synchronized between each other. Use carefully.false
sophora.client.misc.useACSEnables this client to use an additional content server, if enabled in the cluster.false
sophora.client.misc.useReadAnywhereDefines whether this client should also read content from appropriate replica server.false
sophora.client.misc.listeningToDerivedDocumentChangesDefines whether the client should listen to com.subshell.sophora.api.event.DerivedDocumentChangedEvents.
As of version 5 DerivedDocumentChangedEvent are always broadcasted, this configuration option is depreacted and will be removed from version 5.

Configuration of the ToolInfo

sophora.client.toolInfo.enabledIf enabled, the application will be registered as a tool.false
sophora.client.toolInfo.nameThe name of the toolDefaults to the application name or the artifact id.
sophora.client.toolInfo.hostnameThe hostname of the tool-
sophora.client.toolInfo.httpPortThe HTTP port of the tool-
sophora.client.toolInfo.httpsPortThe HTTPs port of the tool-
sophora.client.toolInfo.jolokiaPathURL path to the jolokia API of the tool-
sophora.client.toolInfo.additionalInfoAdditional tool info as key-value pairs.-

Sophora tools may be present in the list of tools within the Sophora Dashboard. There is also an HTTP endpoint in the Content-API, which lists the currently connected tools in a JSON representation.

Sophora Health Indicator

To enable an endpoint showing the client's status (e.g. the server(s) the client is connected to, along with some additional information), edit your application.yaml as follows:

       include: sophora, ...


Spring Boot Sophora Commons exports metrics for the document cache, if the default cache implementation is used. The following metrics are available:

  • sophora_client_cache_documents_hitCount
  • sophora_client_cache_documents_missCount
  • sophora_client_cache_documents_getCount
  • sophora_client_cache_documents_objectCount
  • sophora_client_cache_sophoraIds_hitCount
  • sophora_client_cache_sophoraIds_missCount
  • sophora_client_cache_sophoraIds_getCount
  • sophora_client_cache_sophoraIds_objectCount
  • sophora_client_cache_externalIds_hitCount
  • sophora_client_cache_externalIds_missCount
  • sophora_client_cache_externalIds_getCount
  • sophora_client_cache_externalIds_objectCount

Last modified on 11/23/21

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.