General Update Notes
Version 6 is the first version supporting "decoupled releases", i.e. a relaxation in compatibility between major versions. Most importantly, the Sophora Client 5 remains compatible with Sophora Server 6, so you do not need to update all Sophora products at once during the major update for the Sophora Server.
We will provide a compatibility matrix once more Sophora products are released with different major versions.
Major Changes
The Sophora Client 6 now uses the new gRPC-based Sophora API to communicate with the Sophora Servers. For Client API users, the internal transition to gRPC is transparent and requires no code changes. However, the connection URL must be updated to reflect the new port. By default, the gRPC service is available on port 2026.
Version 5 Clients remain fully compatible with Version 6 Servers, as the server exposes both the new gRPC API and the legacy HTTP API.
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.
Discontinued Support of XPath Queries
With the replacement of JCR by PostgreSQL, XPath queries are no longer supported. Before updating, all XPath queries must be refactored to IQuery.
Affected components:
- API methods accepting XPath query strings.
- The XPathQuery implementation of the IQuery interface.
- The forceRepositorySearch flag.
Unlike XPath queries, which always reflected the immediate, transactional state of the data, Solr-based IQueries are eventually consistent. Results may be outdated by a few seconds. This is generally unproblematic, but if your code reacts to a DocumentChangedEvent and immediately execuites a query, the change that triggered the event might not be represented by the search results.
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 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 | After the update to Sophora Client 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. |
Postgres as the persistence layer
With the release of version 6, Sophora has transitioned its persistence layer from Apache Jackrabbit to PostgreSQL. This shift delivers enhanced performance, greater scalability, and more robust concurrency. See the Document Store documentation for details.
Upon the initial startup of Server version 6, data is automatically migrated from JCR to PostgreSQL. Depending on the size of the repository, this process may take several hours. If the migration is interrupted, it will resume seamlessly upon the next start.
Migration progress can be tracked in the server logs. During the migration process, the server does not open an HTTP port. Thus, it remains inaccessible to clients, metrics are unavailable, and health endpoints do not respond. Make sure your setup does not try to automatically restart the server too quickly due to unresponsiveness.
As with every major release update, replicas must be updated before the primary. While a version 5 primary is compatible with version 6 replicas and staging servers, a version 6 primary is not compatible with version 5 replicas or staging servers.
Once the migration is successfully completed, the JCR repository can be deleted. Both the repository folder in the server's home directory and the associated JCR databases are obsolete. The server must be stopped before deleting the JCR repository.
As a result of this transition, XPath queries are no longer supported. All XPath queries must be migrated to IQuery, which relies on Apache Solr for execution. This affects not only API calls but also text-based configurations in:
- Select Values
- Scripts
- Configurations
These configurations must be refactored to SoQL before starting the update.
The Sophora Server now requires PostgreSQL 17 or later.
Removing obsolete JCR data
Starting with Sophora Server 6.1.0, you can safely remove all data related to JCR after the initial migration. This includes the following directories in your filesystem:
- sophora/repository/repository
- sophora/repository/version
- sophora/repository/workspaces
- sophora/data/tags
You may also delete the database that stores JCR data.
In case you are using our Helm Chart, make sure to update the Helm Chart to at least version 3.0.1. Now apply the following steps in order to delete the old data:
- Set
sophora.server.persistence.repositoryTypetonone - Configure an extra volume mount to access the old data:
extraVolumeMounts:
- name: sophora-server-storage
mountPath: /sophora/old_data
- Remove all obsolete directories via shell access
rm -rf /sophora/old_data/config
rm -rf /sophora/old_data/solr
rm -rf /sophora/old_data/repository.binarystore
rm -rf /sophora/old_data/repository.version
rm -rf /sophora/old_data/repository.binaries
rm -rf /sophora/old_data/repository.workspaces.live.index
rm -rf /sophora/old_data/repository.workspaces.live.db
rm -rf /sophora/old_data/repository.workspaces.default.index
rm -rf /sophora/old_data/repository.workspaces.default.db
rm -rf /sophora/old_data/repository.repository
rm -rf /sophora/data/tags
You can remove the old_data volume mount afterwards.
The Sophora Server now hosts a new gRPC-based Sophora API on an additional port (default 2026).
Due to the discontinuation of Spring Remoting, the Sophora Client (version 6 and later) now utilizes gRPC for server communication. This gRPC services listens on port 2026 by default. Sophora Server 6 exposes both the gRPC and the legacy HTTP API. Consequently, the Sophora Client in 5 remains compatible with Sophora Server 6.
Deprecation Warning: Starting with Sophora Server version 7, the HTTP API will be removed, and only gRPC will be supported.
The module Linkchecker has been sourced out in version 5 and has been removed from Sophora Server 6.
Consequently, the Linkchecker must be deployed as a standalone application.
Content-API Externalization
Up to Version 5, the Content-API was an integral part of the Sophora Server. Starting with Version 6, the Content-API is available exclusively as an external service. Consequently, it must be deployed separately if required.
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.
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 stored 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. |
