General Update Notes (Draft)
This document outlines changes in the upcoming Sophora 6 release. Please note that this is a work in progress—additional sections will be added over time, and details are subject to change before the final release.
Major Changes
The Sophora Client 6 now uses the new gRPC-based Sophora API to communicate with the Sophora Servers.
Unauthenticated Calls
Previously, calling methods on a not-logged-in Sophora Client resulted in undefined behaviour, most of the time throwing exceptions related to network errors. Now these calls will result in the exception ClientStateException, which has two sub-types to further indicate the issue.
Before Login: If the client attempts to send a request to the server before logging in, an exeption is thrown: SophoraClientAwaitingLoginException. There are some logical exceptions that do not require authentication, for example, the login method.
After Logout: If the Sophora Client attempts to send a request to the server after logout, it will always throw the exception SophoraClientAlreadyDisposedException. After a logout a new Sophora Client needs to be instantiated in order to make requests again.
Breaking Changes
| Version | Timing | Changes |
|---|---|---|
| 6.0.0 | Before the update to Sophora Client 6.0.0. | All searches using the IQuery interface will query SolrCloud. The flag SearchParameters forceRepositorySearch will be ignored by the Sophora Server. A warning is logged, if it is still in use. |
| 6.0.0 | After the update to Sophora Client 6.0.0. | This is relevant if you are not using the NodeStateRestorer in com.subshell.sophora.commons instead of the method ISophoraClient#doAndRestoreState(). The NodeStateRestorer was moved from com.subshell.sophora.commons.content to com.subshell.sophora.client.documentstate. |
| 6.0.0 | After the update to Sophora Client 6.0.0. | The copy constructor of SearchParameters changed its visibility to protected. Use SearchParameters#copy instead. |
| 6.0.0 | After the update to Sophora Client 6.0.0. | SolrSearchParameters#getBqs and SolrSearchParameters#getFl now return unmodifiable lists. |
| 6.0.0 | Before the update to Sophora Client 6.0.0. | ServerNode#setNodes now only accepts a list of ServerNodes as the childNodes parameter. If the list contains any elements of other implementations of INode, it will not be set and an exeption IllegalArgumentException will be thrown. |
| 6.0.0 | The dependency org.apache.httpcomponents:httpclient has been replaced by org.apache.httpcomponents.client5:httpclient5. | |
| 6.0.0 | Before the update to Sophora Client 6.0.0. | The Sophora Client now uses a new gRPC-based API to communicate with the Sophora Server. This comes with its own list of breaking changes: "Sophora 6: API changes". Read the page carefully and see if any of your own tools uses one of the deprecated methods. |
| 6.0.0 | Before the update to Sophora Client 6.0.0. | Methods for exporting content to files in Sophora XML or Excel format have been moved from the Sophora Client to a new library with the Maven coordinates com.subshell.sophora.export:sophora-export-library. |
Minimum Sophora Version prior to Upgrade
For compatibility reasons all of your Sophora Servers must be running with at least version 5.11.0 prior to the upgrade to 6.
Major changes in Version 6
Sophora Server version 6 comes with the following changes:
- The Sophora Server now hosts a new gRPC-based Sophora API on an additional port (default 2026).
- The module Linkchecker has been sourced out in version 5 and has been removed from Sophora Server 6.
- The Sophora Server
IQuerysearch API now only allows to search in SolrCloud. XPath queries (deprecated in 5) have been removed. - The Sophora Server now requires PostgreSQL 17 or later.
Document Store configuration
Several new configuration options have been added for the Document Store in Sophora 6.
| Status | Document Store configuration | Description | Default |
|---|---|---|---|
| NEW | sophora.documentstore.sophoraids.declutter.cron | Schedules cleanup of the Sophora ID table. Removes IDs of fully deleted documents if their ID base is continued by other documents. | 0 0 0 * * * (00:00) |
| NEW | sophora.documentstore.cache.documents.maxSize | Document cache located directly behind the database. Prevents database lookups when fetching documents. Stores live and working versions. | 5000 |
| NEW | sophora.documentstore.cache.summaries.maxSize | Document summary cache located directly behind the database. Prevents database lookups when fetching summaries. Stores live and working versions. | 5000 |
| NEW | sophora.documentstore.cache.ids.maxSize | Document ID cache located directly behind the database. Used for resolving references and executing simple queries. Stores live and working versions. | 100000 |
| NEW | sophora.documentstore.cache.primaryTypes.maxSize | Resolves the primary type of a document based on its document ID. | 100000 |
| NEW | sophora.proposals.cache.maxSections | Maximum number of proposal sections stored in the cache. | 2000 |
| NEW | sophora.proposals.cache.maxProposals | Maximum number of proposals stored in the cache. | 20000 |
| NEW | sophora.repository.jcrNodeTypes | Path to a .cnd file containing old JCR definitions that aren't sored in PostgreSQL. The default includes all required JCR nodetypes. It is unlikely that you need to change this property. | classpath:/cnd/jcr.cnd |
| REMOVED | sophora.backupSystemDocuments.cronExpression | Automatic backup of user settings is no longer supported. | — |
| REMOVED | sophora.autoPublish.legacyMode | The released status is no longer considered during publishing. | — |
| REMOVED | sophora.repository.transaction.uuidlocks.enabled | This lock is no longer needed due to the updated transaction model in the Document Store. | — |
PostgreSQL configuration
The PostgreSQL configuration has been available since Sophora 5 but is included here for completeness.
| Property | Description | Default |
|---|---|---|
sophora.persistence.postgres.hostname | Hostname of the PostgreSQL server | — |
sophora.persistence.postgres.port | Port of the PostgreSQL server | — |
sophora.persistence.postgres.username | PostgreSQL username | — |
sophora.persistence.postgres.password | PostgreSQL password | — |
sophora.persistence.postgres.database | Database used for both Version Store and Document Store | — |
sophora.persistence.postgres.maxPoolSize | Maximum number of connections in the connection pool. Determines how many SQL requests can be processed in parallel. Connections are reused. | 10 |
sophora.persistence.postgres.minIdleConnections | Minimum number of connections that should always be available | — |
sophora.persistence.postgres.connectionTimeoutMs | Maximum time the Sophora Server waits for a connection | 30000 (30s) |
sophora.persistence.postgres.idleTimeoutMs | Maximum time a connection should remain idle before being closed | 10000 (10s) |
sophora.persistence.postgres.validationTimeoutMs | After this timeout, the Sophora Server checks the connection’s health status | 5000 (5s) |
sophora.persistence.postgres.sslMode | Sets the SSL mode. To enforce a connection over TLS use require. For more information about SSL modes refer to the official postgres documentation. | prefer (Postgres default) |
List of breaking changes
| Version | Timing | Changes |
|---|---|---|
| 6.0.0 | Before the update, preferably months before | The Sophora Server does no longer come with an internal Linkchecker. If you use this feature and have not yet switched to the external Linkchecker application, you should install it before updating. |
| 6.0.0 | Before the update, preferably months before | Support for the legacy structure node document type "sophora-nt:structureNodeDocument" is discontinued in version 6. Please ensure that you do not use this document type anywhere. Since version 3 it is replaced by "sophora-nt:structureNode2". |
| 6.0.0 | Before the update, preferably months before | The Sophora Server no longer supports to search its PostgreSQL based document repository with IQuerys. Instead all queries will search in SolrCloud. The SearchParameters forceRepositorySearch flag will be ignored by the Sophora Server. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server has a default implementation for composing and parsing URLs, which uses the URL components of the Sophora Webapp-Framework instead of requesting the deliveries.This implementation can handle both Sophora document URLs and URLs for the Sophora Image Service. It also avoids HTTP calls to the deliveries and thus it's much faster. Using the URL handling from the deliveries by setting the property sophora.url.use-url-library=false in the configuration file is no longer possible. The configuration sophora.documentUuidProvider.servletPath has also been removed.For more information about the properties, see the description in the documentation of the Sophora Server configuration. |
| 6.0.0 | Before the update, preferably months before | Since the method getAdditionalXPath (deprecated in 5) was removed from the ITimingActionScript interface, all implementations must also omit this method. Use getAdditionalIQuery as replacement. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server no longer natively supports HTTPS and all associated configuration options have been removed. We highly recommend using an SSL-terminating reverse-proxy like nginx to connect to the Sophora Server. Read the configuration guide for more information how to configure Sophora correctly. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server now hosts the new gRPC-based Sophora API on an additional port (default 2026). The previous API remains but will be removed with the future Sophora Server 7 release. The new API comes with its own list of breaking changes, which can be found on the "Sophora 6: API changes" page. Read the page carefully and see, if any of your own tools uses one of the deprecated methods. |
| 6.0.0 | Before the update, preferably months before | The shell script sophoraServerControl.sh, previously used to start the Sophora Server for on-premises setups, was removed in version 6 (was deprecated in 5). Customers can still run the Sophora Server on-premise, but no official script will be provided or supported. The recommended deployment method is now container-based/cloud-based using Helm charts. |
| 6.0.0 | Before the update, preferably months before | We removed the support for the deprecated sophora-nt:tags node type. The method com.subshell.sophora.api.server.IContentManagerContent#getTags will not be removed in Sophora 6 but it will always return an empty set. Related to this change the following sophora.properties configurations were removed:
|
| 5.12.0, 6.0.0 | Before the update | A BooleanQuery without any subqueries will now lead to an exception in the server, instead of interpreting it as a "find everything" query. Tools may create such queries when generating a BooleanQuery by using an empty list. |
