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. |
