Changelog

Sophora 6: API changes (Draft)

Major API changes in the upcoming Sophora 6 version.

Disclaimer

Overview

Sophora 6 introduces a new internal API based on gRPC, bringing significant architectural changes. As a result:

  • Some existing methods are no longer supported due to technical or security-related reasons.
  • New methods and features have been added.
  • Others have been renamed or restructured for clarity.

These changes mainly affect the deprecated internal API, the IContentManager. Since the public ISophoraClient API provides access to IContentManager in earlier versions, some of your existing scripts or applications may also be impacted.

Transition Notes

  • Compatibility mode: In Sophora 6, the server still supports ContentManager for V5 Sophora Clients and Server-side scripts. However, you should stop using any deprecated methods listed below.
  • JavaDoc is your friend: Always check the JavaDoc for annotations. Avoid using deprecated methods—they won’t be around for long.

Key changes

Notable changes in IContentManager

IContentManager is no longer available in Sophora Client V6. These notes may still be useful for server-executed scripts:

MethodStatusNotes
solrRawQueryRemovedUse IQuery or SoQL for searches

Changes in ISophoraClient

MethodStatusNotes
findDocuments(String soqlString)NewSearch documents using SoQL
findDocumentIds(String soqlString)NewQuery document IDs using SoQL
isReadAnywhereActiveNewIndicates if ReadAnywhere mode is active
getAvailableReadAnywhereReplicasNewLists ReadAnywhere replicas
requestDocumentLock, grantLock, rejectLockRequestNewUseful for coordinated editing
getSelectValuesFromDefaultPropertyConfigurationNewReturns the calculated SelectValues to a default property configuration. Until now, it was only possible to get the SelectValues for a specific property and node type combination.
withTimeoutAfter(Duration)NewThis method can be used to create a time-boxed facade over the existing client, where all requests adhere to the given timeout and throw an exception if it is exceeded. By default, a client has no timeout. You can use this method either for a single API call or store the created facade in a variable to make multiple requests with the same timeout. In any case, it is always the same client.

Example:
client.withTimeoutAfter(Duration.ofSeconds(2)).getDocumentBySophoraId("home100");
saveSophoraDocumentChangedThe preserveHistory flag has been removed / has no effect anymore.
getContentManagerRemovedUse only ISophoraClient methods
publishToExternalServiceRemovedUse the new HttpClient in scripts
getTagsRemovedThis was from an older system; not related to the Taxo API
getDocumentVersionsByUuidRemovedRemoved for performance reasons. Alternatives are available
isApiMatchingRemovedInternal use only. Listed for completeness
sendDataToUrl, getDataFromUrlRemovedUse HttpClient directly
getCompressedDictionary, saveDictionary(String name, byte[] wordsData)RemovedOnly used internally. Listed for completeness
getCndHashEntries, getDocumentProposalSectionHashEntries, getStructureNodeDocumentHashEntries, getSystemDocumentHashEntriesRemovedNow available via Sophora Server HTTP endpoints
sendServerEvent, getServerEventsRemovedInternal use only. Listed for completeness.
reconnectOnNonMatchingAPIRemovedThe reconnection logic has changed
isReadAnywhereModeRemovedUse isReadAnywhereActive() instead
getAvailableReadOnlyContentManagersRemovedUse getAvailableReadAnywhereReplicas() instead
reconnectTo, getProtocol, getConnectionBarrierRemovedListed for completeness

Other notable changes

  • DeskClientSettings, ImageVariant, SelectValues, and Channel now return document IDs in a new wrapper object.
  • UserChangedEvent now return just the username instead of the full user object.
  • IUserListener method now receives just the username instead of a full user object.
  • SophoraClientFactory has been removed. Use SophoraClientBuilder instead.
  • Proxy settings have been removed from SophoraClientBuilder. Use JVM proxy properties.
  • Use withNetworkConnectionData instead of withAuthorizationHeaderSupplier in SophoraClientBuilder.
  • The Cluster feature for Sophora Staging Servers has been removed (still available for Sophora Primary Servers.)
  • Binary data is now transferred in chunks, reducing HTTP message size. Binary data is stored separately and linked via references.Scripts must work with BinaryReferenceValues and manually resolve the data.

The following methods have been removed from IValidationScriptDocumentManager:

  • findDocumentUuids(String xPathQuery, int pageIndex, int pageSize)
  • getDocumentVersionsByUuid(UUID uuid, int count, TimeRange timeRange)
  • getDocumentFromVersion(UUID versionUuid)

Known incompatibilities (V5 → V6)

  • XPath queries are no longer supported in Sophora Server V6. Use IQuery or SoQL.
  • Lock requests for documents by editors or tools can only be made between V5 Clients or among V6 Clients. This affects features like the “Polite Import,” and also applies in mixed environments where both V5 and V6 Sophora Clients are used.

Changed behavior: Connection losses

In Sophora 6, if the Client loses the connection to the Primary Server (or a Staging Server):

It will retry the connection a fixed number of times based on:

  • connectRetries
  • connectRetryIntervalInSeconds

If a client is unable to reconnect to a server, it switches into an broken state. Methods on the client will then respond with the new ConnectionLostInTheVoid exception. If a client user receives this exception, you'll need to recover it manually or with custom logic.

Changed behavior: Unauthenticated calls

Also new is the client’s behavior before login and after logout:

  • If the client makes a request to the server without being logged in, a SophoraClientAwaitingLoginException is thrown. There are some methods for which no authentication is required, such as login or logout.
  • If the client makes a request to the server after logging out, it will always be terminated with a SophoraClientAlreadyDisposedException.

Both exceptions inherit from ClientStateException, which in turn inherits from SophoraException.

Additional API server

The new gRPC based API is hosted on a separate port (default 2026). This may require additional configuration during the upgrade (e.g. reverse proxies, configuration files of client tools connecting via the new API etc.).

PropertyDefaultDescription
sophora.remote.api.grpc.enabledtrueDisables or enables the gRPC endpoint.
sophora.remote.api.grpc.port2026Additional server port for gRPC.
sophora.remote.api.grpc.debugfalseDisables or enables grpc debug mode.
sophora.remote.api.grpc.external.protocolExternal grpc protocol. Typically used in Kubernetes environments.
sophora.remote.api.grpc.external.hostnameExternal grpc hostname. Typically used in Kubernetes environments.
sophora.remote.api.grpc.external.portExternal grpc port. Typically used in Kubernetes environments.

Last modified on 11/19/24

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

Icon