Upgrade
On upgrading from a 2.x release, all Couchbase Lite databases will be automatically re-indexed on initial database open. |
3.1.10 Upgrade
This upgrade requires all 2.x databases be reindexed on initial open. |
The action will take place automatically and can lead to some delay in the database becoming available for use in your application.
In addition, if you are syncing with a 3.1.10 Sync Gateway, you should be aware of the significant configuration enhancements introduced and their impact. This is a one-way conversion.
API Changes
This content introduces the changes made to the Couchbase Lite for Java API for release 3.1.10.
Removed
ResetCheckpoint
The method Replicator.resetCheckpoint() method has been removed.
Instead, use Replicator.resetCheckpoint(boolean reset).
replicator.resetCheckpoint()
replicator.start()
replicator.start(true)
Database.setLogLevel
The method Database.setLogLevel()
has been removed.
Instead:
-
Set the logging levels for loggers, individually
-
Set the domains to be logged by the console logger, explicitly.
Database.setLogLevel(LogDomain.ALL, LogLevel.VERBOSE)
Database.log.getConsole().setDomains(LogDomain.ALL_DOMAINS)
Database.log.getConsole().setLevel(LogLevel.VERBOSE)
Database.log.getFile().setDomains(LogLevel.DEBUG)
Database.compact
The Database.compact() method has been removed.
It is replaced by the new Database.performMaintenance(MaintenanceType) method, and the maintenance operations represented in the enum MaintenanceType
try testdb.compact()
testdb.performMaintenance(MaintenanceType.COMPACT)
Deprecated in the API
MATCH
The class, FullTextExpression
has been deprecated.
Use FullTextFunction instead.
FullTextExpression index = FullTextExpression.index("indexName")
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(index.match(queryString))
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(FullTextFunction.match("indexName", queryString))
isNullOrMissing/notNullOrMissing
The functions Expression.isNullOrMissing and Expression.notNullOrMissing have been deprecated.
Use isNotValued()
and-or isValued()
instead.
Query q =
QueryBuilder
.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(
Expression.property("missingProp").isNullOrMissing())
Query q =
QueryBuilder
.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("notMissingProp").notNullOrMissing())
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("missingProp").isNotValued())
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("notMissingProp").isValued())
AbstractReplicatorConfiguration
The enum AbstractReplicatorConfiguration.ReplicatorType
and the methods
ReplicatorConfiguration.setReplicatorType
and
ReplicatorConfiguration.getReplicatorType
have all been deprecated.
Instead, use the methods ReplicatorConfiguration.setType
and ReplicatorConfiguration.getType
, and the top level enum ReplicatorType
.
ReplicatorConfiguration config =
new ReplicatorConfiguration().setReplicatorType(ReplicatorConfiguration.ReplicatorType.PUSH_AND_PULL);
ReplicatorConfiguration config =
new ReplicatorConfiguration().setType(ReplicatorType.PUSH_AND_PULL);
Moved in the API
The enum AbstractReplicator.ActivityLevel and the classes AbstractReplicator.Progress and AbstractReplicator.Status have all been moved to be top level definitions.
They are replaced by these definitions:
ListenerToken token =
replicator.addChangeListener(
testSerialExecutor,
change -> {
final AbstractReplicator.Status status = change.getStatus()
if (status.getActivityLevel() == AbstractReplicator.ActivityLevel.BUSY)
{ AbstractReplicator.Progress progress =
status.getProgress(); Logger.log("Progress: " + progress.completed + "/" progress.total);
}
});
ListenerToken token =
replicator.addChangeListener(
testSerialExecutor,
change -> {
final ReplicatorStatus status = change.getStatus()
if (status.getActivityLevel() == ReplicatorActivityLevel.BUSY)
{ ReplicatorProgress progress =
status.getProgress(); Logger.log("Progress: " + progress.completed + "/" progress.total);
}
});
1.x Databases Upgrades to 2.x
Databases created using Couchbase Lite 1.2 or later can still be used with Couchbase Lite 2.x; but will be automatically updated to the current 2.x version. This feature is only available for the default storage type (i.e., not a ForestDB database).
Encrypted Databases
The automatic migration feature does not support encrypted databases. So if the 1.x database is encrypted you will first need to disable encryption using the Couchbase Lite 1.x API (see the 1.x Database Guide).
Thus, to upgrade an encrypted 1.x database, you should do the following:
Since it is not possible to package Couchbase Lite 1.x and Couchbase Lite 2.x in the same application this upgrade path would require two successive upgrades.
If you are using Sync Gateway to synchronize the database content, it may be preferable to run a pull replication from a new 2.x database with encryption enabled and delete the 1.x local database.
Handling of Existing Conflicts
If there are existing conflicts in the 1.x database, the automatic upgrade process copies the default winning revision to the new database and does NOT copy any conflicting revisions.
This functionality is related to the way conflicts are now being handled in Couchbase Lite — see Handling Data Conflicts.
Optionally, existing conflicts in the 1.x database can be resolved with the 1.x API prior to the database being upgraded.
Handling of Existing Attachments
Attachments persisted in a 1.x database are copied to the new database.
NOTE: The relevant Couchbase Lite API is now called the Blob
API not the Attachments
API.
The functionally is identical but the internal schema for attachments has changed.
Blobs are stored anywhere in the document, just like other value types.
Whereas in 1.x they were stored under the _attachments
field.
The automatic upgrade functionality does not update the internal schema for attachments, so they remain accessible under the _attachments
field.
See Example 1 for how to retrieve an attachment that was created in a 1.x database with a 2.x API.
Dictionary attachments = document.getDictionary("_attachments");
Blob blob = attachments != null ? attachments.getBlob("avatar") : null;
byte[] content = blob != null ? blob.getContent() : null;
Replication Compatibility
The current replication protocol is not backwards compatible with the 1.x replication protocol. Therefore, to use replication with Couchbase Lite 2.x, the target Sync Gateway instance must also be upgraded to 2.x.
Sync Gateway 2.x will continue to accept clients that connect through the 1.x protocol. It will automatically use the 1.x replication protocol when a Couchbase Lite 1.x client connects through http://localhost:4984/db and the 2.0 replication protocol when a Couchbase Lite 2.0 client connects through ws://localhost:4984/db. This allows for a smoother transition to get all your user base onto a version of your application built with Couchbase Lite 2.x.