/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.content;
import android.database.Cursor;
import android.database.sqlite.SQLiteDatabase;
import android.net.Uri;
import java.util.Map;
/**
* A specialization of the ContentProvider that centralizes functionality
* used by ContentProviders that are syncable. It also wraps calls to the ContentProvider
* inside of database transactions.
*
* @hide
*/
public abstract class SyncableContentProvider extends ContentProvider {
protected abstract boolean isTemporary();
/**
* Close resources that must be closed. You must call this to properly release
* the resources used by the SyncableContentProvider.
*/
public abstract void close();
/**
* Override to create your schema and do anything else you need to do with a new database.
* This is run inside a transaction (so you don't need to use one).
* This method may not use getDatabase(), or call content provider methods, it must only
* use the database handle passed to it.
*/
protected abstract void bootstrapDatabase(SQLiteDatabase db);
/**
* Override to upgrade your database from an old version to the version you specified.
* Don't set the DB version, this will automatically be done after the method returns.
* This method may not use getDatabase(), or call content provider methods, it must only
* use the database handle passed to it.
*
* @param oldVersion version of the existing database
* @param newVersion current version to upgrade to
* @return true if the upgrade was lossless, false if it was lossy
*/
protected abstract boolean upgradeDatabase(SQLiteDatabase db, int oldVersion, int newVersion);
/**
* Override to do anything (like cleanups or checks) you need to do after opening a database.
* Does nothing by default. This is run inside a transaction (so you don't need to use one).
* This method may not use getDatabase(), or call content provider methods, it must only
* use the database handle passed to it.
*/
protected abstract void onDatabaseOpened(SQLiteDatabase db);
/**
* Get a non-persistent instance of this content provider.
* You must call {@link #close} on the returned
* SyncableContentProvider when you are done with it.
*
* @return a non-persistent content provider with the same layout as this
* provider.
*/
public abstract SyncableContentProvider getTemporaryInstance();
public abstract SQLiteDatabase getDatabase();
public abstract boolean getContainsDiffs();
public abstract void setContainsDiffs(boolean containsDiffs);
/**
* Each subclass of this class should define a subclass of {@link
* AbstractTableMerger} for each table they wish to merge. It
* should then override this method and return one instance of
* each merger, in sequence. Their {@link
* AbstractTableMerger#merge merge} methods will be called, one at a
* time, in the order supplied.
*
* <p>The default implementation returns an empty list, so that no
* merging will occur.
* @return A sequence of subclasses of {@link
* AbstractTableMerger}, one for each table that should be merged.
*/
protected abstract Iterable<? extends AbstractTableMerger> getMergers();
/**
* Check if changes to this URI can be syncable changes.
* @param uri the URI of the resource that was changed
* @return true if changes to this URI can be syncable changes, false otherwise
*/
public abstract boolean changeRequiresLocalSync(Uri uri);
/**
* Called right before a sync is started.
*
* @param context the sync context for the operation
* @param account
*/
public abstract void onSyncStart(SyncContext context, String account);
/**
* Called right after a sync is completed
*
* @param context the sync context for the operation
* @param success true if the sync succeeded, false if an error occurred
*/
public abstract void onSyncStop(SyncContext context, boolean success);
/**
* The account of the most recent call to onSyncStart()
* @return the account
*/
public abstract String getSyncingAccount();
/**
* Merge diffs from a sync source with this content provider.
*
* @param context the SyncContext within which this merge is taking place
* @param diffs A temporary content provider containing diffs from a sync
* source.
* @param result a MergeResult that contains information about the merge, including
* a temporary content provider with the same layout as this provider containing
* @param syncResult
*/
public abstract void merge(SyncContext context, SyncableContentProvider diffs,
TempProviderSyncResult result, SyncResult syncResult);
/**
* Invoked when the active sync has been canceled. The default
* implementation doesn't do anything (except ensure that this
* provider is syncable). Subclasses of ContentProvider
* that support canceling of sync should override this.
*/
public abstract void onSyncCanceled();
public abstract boolean isMergeCancelled();
/**
* Subclasses should override this instead of update(). See update()
* for details.
*
* <p> This method is called within a acquireDbLock()/releaseDbLock() block,
* which means a database transaction will be active during the call;
*/
protected abstract int updateInternal(Uri url, ContentValues values,
String selection, String[] selectionArgs);
/**
* Subclasses should override this instead of delete(). See delete()
* for details.
*
* <p> This method is called within a acquireDbLock()/releaseDbLock() block,
* which means a database transaction will be active during the call;
*/
protected abstract int deleteInternal(Uri url, String selection, String[] selectionArgs);
/**
* Subclasses should override this instead of insert(). See insert()
* for details.
*
* <p> This method is called within a acquireDbLock()/releaseDbLock() block,
* which means a database transaction will be active during the call;
*/
protected abstract Uri insertInternal(Uri url, ContentValues values);
/**
* Subclasses should override this instead of query(). See query()
* for details.
*
* <p> This method is *not* called within a acquireDbLock()/releaseDbLock()
* block for performance reasons. If an implementation needs atomic access
* to the database the lock can be acquired then.
*/
protected abstract Cursor queryInternal(Uri url, String[] projection,
String selection, String[] selectionArgs, String sortOrder);
/**
* Make sure that there are no entries for accounts that no longer exist
* @param accountsArray the array of currently-existing accounts
*/
protected abstract void onAccountsChanged(String[] accountsArray);
/**
* A helper method to delete all rows whose account is not in the accounts
* map. The accountColumnName is the name of the column that is expected
* to hold the account. If a row has an empty account it is never deleted.
*
* @param accounts a map of existing accounts
* @param table the table to delete from
* @param accountColumnName the name of the column that is expected
* to hold the account.
*/
protected abstract void deleteRowsForRemovedAccounts(Map<String, Boolean> accounts,
String table, String accountColumnName);
/**
* Called when the sync system determines that this provider should no longer
* contain records for the specified account.
*/
public abstract void wipeAccount(String account);
/**
* Retrieves the SyncData bytes for the given account. The byte array returned may be null.
*/
public abstract byte[] readSyncDataBytes(String account);
/**
* Sets the SyncData bytes for the given account. The bytes array may be null.
*/
public abstract void writeSyncDataBytes(String account, byte[] data);
}