Nota: Recomendamos WorkManager como la solución más apropiada para la mayoría de los casos prácticos de procesamiento en segundo plano. Consulta la guía de procesamiento en segundo plano para conocer la solución que funcionará mejor en tu caso.
El componente del adaptador de sincronización de tu app encapsula el código para las tareas que transfieren datos entre el dispositivo y un servidor. Según la programación y los activadores que proporcionas en tu app, el marco de trabajo del adaptador de sincronización ejecuta el código en el componente del adaptador de sincronización. Para agregar un componente de adaptador de sincronización a tu app, debes agregar los siguientes elementos:
- Clase de adaptador de sincronización.
- Una clase que une el código de transferencia de datos en una interfaz compatible con el framework del adaptador de sincronización.
Servicevinculado.- Un componente que permite que el framework del adaptador de sincronización ejecute el código en la clase de tu adaptador de sincronización.
- Archivo de metadatos XML del adaptador de sincronización.
- Un archivo con información sobre tu adaptador de sincronización. El framework lee el archivo para determinar cómo se debe cargar y programar la transferencia de datos.
- Declaraciones en el manifiesto de la app.
- Un archivo XML que declara el servicio vinculado y apunta a metadatos específicos del adaptador de sincronización.
En esta lección, se muestra cómo definir esos elementos.
Cómo crear una clase de adaptador de sincronización
En esta parte de la lección, aprenderás a crear la clase de adaptador de sincronización que encapsula el código de transferencia de datos. La creación de la clase incluye extender la clase base del adaptador de sincronización, definir constructores para la clase e implementar el método en el que se definen las tareas de transferencia de datos.
Cómo extender la clase de adaptador de sincronización de base
Para crear el componente del adaptador de sincronización, extiende AbstractThreadedSyncAdapter y escribe los constructores. Usa los constructores a fin de ejecutar tareas de configuración cada vez que crees desde cero el componente adaptador de sincronización, igual que usas Activity.onCreate() para configurar una actividad. Por ejemplo, si la app usa un proveedor de contenido para almacenar datos, utiliza los constructores a fin de obtener una instancia de ContentResolver. Debido a que se agregó una segunda forma del constructor en la versión 3.0 de la plataforma de Android para admitir el argumento parallelSyncs, debes crear dos formas del constructor a fin de mantener la compatibilidad.
Nota: El framework del adaptador de sincronización está diseñado para funcionar con componentes del adaptador de sincronización que son instancias singleton. La creación de instancias del componente del adaptador de sincronización se analizará con más detalles en la sección Cómo vincular el adaptador de sincronización con el framework.
En el siguiente ejemplo, se muestra cómo implementar AbstractThreadedSyncAdapter y sus constructores:
Kotlin
/**
* Handle the transfer of data between a server and an
* app, using the Android sync adapter framework.
*/
class SyncAdapter @JvmOverloads constructor(
context: Context,
autoInitialize: Boolean,
/**
* Using a default argument along with @JvmOverloads
* generates constructor for both method signatures to maintain compatibility
* with Android 3.0 and later platform versions
*/
allowParallelSyncs: Boolean = false,
/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/
val mContentResolver: ContentResolver = context.contentResolver
) : AbstractThreadedSyncAdapter(context, autoInitialize, allowParallelSyncs) {
...
}
Java
/**
* Handle the transfer of data between a server and an
* app, using the Android sync adapter framework.
*/
public class SyncAdapter extends AbstractThreadedSyncAdapter {
...
// Global variables
// Define a variable to contain a content resolver instance
ContentResolver contentResolver;
/**
* Set up the sync adapter
*/
public SyncAdapter(Context context, boolean autoInitialize) {
super(context, autoInitialize);
/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/
contentResolver = context.getContentResolver();
}
...
/**
* Set up the sync adapter. This form of the
* constructor maintains compatibility with Android 3.0
* and later platform versions
*/
public SyncAdapter(
Context context,
boolean autoInitialize,
boolean allowParallelSyncs) {
super(context, autoInitialize, allowParallelSyncs);
/*
* If your app uses a content resolver, get an instance of it
* from the incoming Context
*/
contentResolver = context.getContentResolver();
...
}
Cómo agregar el código de transferencia de datos
El componente del adaptador de sincronización no hace la transferencia de datos automáticamente. En cambio, encapsula tu código de transferencia de datos, de modo que el framework del adaptador de sincronización pueda ejecutar la transferencia de datos en segundo plano, sin la participación de la app. Cuando el framework está listo para sincronizar los datos de la app, invoca la implementación del método onPerformSync().
Para facilitar la transferencia de datos desde el código principal de la app al componente del adaptador de sincronización, el framework del adaptador de sincronización llama a onPerformSync() con los siguientes argumentos:
- Cuenta
- Un objeto
Accountasociado con el evento que activó el adaptador de sincronización. Si el servidor no usa cuentas, no necesitas usar la información de este objeto. - Extras
- Un
Bundlecon marcas enviadas por el evento que activó el adaptador de sincronización. - Autoridad
- La autoridad de un proveedor de contenido en el sistema. La app debe tener acceso a este proveedor. Por lo general, la autoridad corresponde a un proveedor de contenido de tu propia app.
- Cliente proveedor de contenido
- Un
ContentProviderClientpara el proveedor de contenido al que apunta el argumento de autoridad. UnContentProviderClientes una interfaz pública básica para un proveedor de contenido. Tiene la misma funcionalidad básica que unContentResolver. Si usas un proveedor de contenido para almacenar datos de tu app, puedes conectarte con el proveedor que tenga este objeto. De lo contrario, puedes ignorarlo. - Resultado de la sincronización
- Un objeto
SyncResultque se usa para enviar información al framework del adaptador de sincronización.
En el siguiente fragmento, se muestra la estructura general de onPerformSync():
Kotlin
/*
* Specify the code you want to run in the sync adapter. The entire
* sync adapter runs in a background thread, so you don't have to set
* up your own background processing.
*/
override fun onPerformSync(
account: Account,
extras: Bundle,
authority: String,
provider: ContentProviderClient,
syncResult: SyncResult
) {
/*
* Put the data transfer code here.
*/
}
Java
/*
* Specify the code you want to run in the sync adapter. The entire
* sync adapter runs in a background thread, so you don't have to set
* up your own background processing.
*/
@Override
public void onPerformSync(
Account account,
Bundle extras,
String authority,
ContentProviderClient provider,
SyncResult syncResult) {
/*
* Put the data transfer code here.
*/
}
Si bien la implementación real de onPerformSync() es específica para los requisitos de sincronización de datos de la app y los protocolos de conexión del servidor, hay algunas tareas generales que tu implementación debe realizar:
- Conexión con un servidor
- Aunque se puede suponer que la red está disponible cuando se inicia la transferencia de datos, el framework del adaptador de sincronización no se conecta automáticamente a un servidor.
- Descarga y carga de datos
- Un adaptador de sincronización no automatiza ninguna tarea de transferencia de datos. Si quieres descargar datos de un servidor y almacenarlos en un proveedor de contenido, debes proporcionar el código que solicita los datos, los descarga y los inserta en el proveedor. Del mismo modo, si quieres enviar datos a un servidor, debes leerlos desde un archivo, una base de datos o un proveedor y enviar la solicitud de carga necesaria. También debes solucionar los errores de red que se producen mientras se ejecuta la transferencia de datos.
- Control de los conflictos de datos o determinación de actualidad de los datos
- Un adaptador de sincronización no controla automáticamente los conflictos entre los datos del servidor y los del dispositivo. Además, no detecta automáticamente si los datos del servidor son más recientes que los del dispositivo, o viceversa. En cambio, debes proporcionar tus propios algoritmos para controlar esta situación.
- Limpieza
- Al final de cada transferencia de datos, siempre debes cerrar las conexiones con un servidor y limpiar los archivos temporales y las memorias caché.
Nota: El framework del adaptador de sincronización se ejecuta en onPerformSync(), en un subproceso en segundo plano, por lo que no necesitas configurar tu procesamiento en segundo plano.
Además de las tareas relacionadas con la sincronización, debes intentar combinar las tareas habituales relacionadas con la red y agregarlas a onPerformSync().
Si concentras todas las tareas de red en este método, conservarás la energía de la batería necesaria para iniciar y detener las interfaces de red. Para obtener más información sobre cómo hacer que el acceso a la red sea más eficiente, consulta la clase de capacitación Cómo transferir datos sin consumir la batería, en la que se describen varias tareas de acceso a la red que puedes incluir en el código de transferencia de datos.
Cómo vincular el adaptador de sincronización con el marco de trabajo
Ahora tienes el código de transferencia de datos encapsulado en un componente de adaptador de sincronización, pero debes proporcionar al framework acceso al código. Para ello, debes crear un Service vinculado que transfiera un objeto vinculante especial de Android del componente del adaptador de sincronización al framework. Con este objeto vinculante, el framework puede invocar el método onPerformSync() y pasarle datos.
Crea una instancia del componente de adaptador de sincronización como singleton en el método onCreate() del servicio. Cuando creas una instancia del componente en onCreate(), pospones la creación hasta que se inicia el servicio, lo que sucede cuando el framework intenta ejecutar la transferencia de datos por primera vez. Debes crear una instancia del componente de manera segura para subprocesos, en caso de que el framework del adaptador de sincronización ponga en cola múltiples ejecuciones del adaptador de sincronización como respuesta a activadores o programación.
Por ejemplo, en el siguiente fragmento, se muestra cómo crear una clase que implementa el Service vinculado, crea una instancia del componente de adaptador de sincronización y obtiene el objeto vinculante de Android:
Kotlin
package com.example.android.syncadapter
/**
* Define a Service that returns an [android.os.IBinder] for the
* sync adapter class, allowing the sync adapter framework to call
* onPerformSync().
*/
class SyncService : Service() {
/*
* Instantiate the sync adapter object.
*/
override fun onCreate() {
/*
* Create the sync adapter as a singleton.
* Set the sync adapter as syncable
* Disallow parallel syncs
*/
synchronized(sSyncAdapterLock) {
sSyncAdapter = sSyncAdapter ?: SyncAdapter(applicationContext, true)
}
}
/**
* Return an object that allows the system to invoke
* the sync adapter.
*
*/
override fun onBind(intent: Intent): IBinder {
/*
* Get the object that allows external processes
* to call onPerformSync(). The object is created
* in the base class code when the SyncAdapter
* constructors call super()
*
* We should never be in a position where this is called before
* onCreate() so the exception should never be thrown
*/
return sSyncAdapter?.syncAdapterBinder ?: throw IllegalStateException()
}
companion object {
// Storage for an instance of the sync adapter
private var sSyncAdapter: SyncAdapter? = null
// Object to use as a thread-safe lock
private val sSyncAdapterLock = Any()
}
}
Java
package com.example.android.syncadapter;
/**
* Define a Service that returns an <code><a href="/reference/android/os/IBinder.html">IBinder</a></code> for the
* sync adapter class, allowing the sync adapter framework to call
* onPerformSync().
*/
public class SyncService extends Service {
// Storage for an instance of the sync adapter
private static SyncAdapter sSyncAdapter = null;
// Object to use as a thread-safe lock
private static final Object sSyncAdapterLock = new Object();
/*
* Instantiate the sync adapter object.
*/
@Override
public void onCreate() {
/*
* Create the sync adapter as a singleton.
* Set the sync adapter as syncable
* Disallow parallel syncs
*/
synchronized (sSyncAdapterLock) {
if (sSyncAdapter == null) {
sSyncAdapter = new SyncAdapter(getApplicationContext(), true);
}
}
}
/**
* Return an object that allows the system to invoke
* the sync adapter.
*
*/
@Override
public IBinder onBind(Intent intent) {
/*
* Get the object that allows external processes
* to call onPerformSync(). The object is created
* in the base class code when the SyncAdapter
* constructors call super()
*/
return sSyncAdapter.getSyncAdapterBinder();
}
}
Nota: Si quieres ver un ejemplo más detallado de un servicio vinculado para un adaptador de sincronización, consulta la app de ejemplo.
Cómo agregar la cuenta obligatoria para el framework
El framework del adaptador de sincronización requiere que cada adaptador de sincronización tenga un tipo de cuenta. Ya declaraste el valor del tipo de cuenta en la sección Cómo agregar el archivo de metadatos del Autenticador. Ahora debes configurar este tipo de cuenta en el sistema Android. A fin de configurar el tipo de cuenta, llama a addAccountExplicitly() para agregar una cuenta ficticia que use el tipo de cuenta.
El mejor lugar para llamar al método es en el método onCreate() de la actividad de apertura de la app. En el siguiente fragmento de código, se muestra cómo hacerlo:
Kotlin
...
// Constants
// The authority for the sync adapter's content provider
const val AUTHORITY = "com.example.android.datasync.provider"
// An account type, in the form of a domain name
const val ACCOUNT_TYPE = "example.com"
// The account name
const val ACCOUNT = "dummyaccount"
...
class MainActivity : FragmentActivity() {
// Instance fields
private lateinit var mAccount: Account
...
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
...
// Create the dummy account
mAccount = createSyncAccount()
...
}
...
/**
* Create a new dummy account for the sync adapter
*/
private fun createSyncAccount(): Account {
val accountManager = getSystemService(Context.ACCOUNT_SERVICE) as AccountManager
return Account(ACCOUNT, ACCOUNT_TYPE).also { newAccount ->
/*
* Add the account and account type, no password or user data
* If successful, return the Account object, otherwise report an error.
*/
if (accountManager.addAccountExplicitly(newAccount, null, null)) {
/*
* If you don't set android:syncable="true" in
* in your <provider> element in the manifest,
* then call context.setIsSyncable(account, AUTHORITY, 1)
* here.
*/
} else {
/*
* The account exists or some other error occurred. Log this, report it,
* or handle it internally.
*/
}
}
}
...
}
Java
public class MainActivity extends FragmentActivity {
...
...
// Constants
// The authority for the sync adapter's content provider
public static final String AUTHORITY = "com.example.android.datasync.provider";
// An account type, in the form of a domain name
public static final String ACCOUNT_TYPE = "example.com";
// The account name
public static final String ACCOUNT = "dummyaccount";
// Instance fields
Account mAccount;
...
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
...
// Create the dummy account
mAccount = CreateSyncAccount(this);
...
}
...
/**
* Create a new dummy account for the sync adapter
*
* @param context The application context
*/
public static Account CreateSyncAccount(Context context) {
// Create the account type and default account
Account newAccount = new Account(
ACCOUNT, ACCOUNT_TYPE);
// Get an instance of the Android account manager
AccountManager accountManager =
(AccountManager) context.getSystemService(
ACCOUNT_SERVICE);
/*
* Add the account and account type, no password or user data
* If successful, return the Account object, otherwise report an error.
*/
if (accountManager.addAccountExplicitly(newAccount, null, null)) {
/*
* If you don't set android:syncable="true" in
* in your <provider> element in the manifest,
* then call context.setIsSyncable(account, AUTHORITY, 1)
* here.
*/
} else {
/*
* The account exists or some other error occurred. Log this, report it,
* or handle it internally.
*/
}
}
...
}
Cómo agregar el archivo de metadatos del adaptador de sincronización
Para conectar el componente del adaptador de sincronización con el marco de trabajo, debes proporcionar metadatos que describan el componente y ofrezcan marcas adicionales. Los metadatos especifican el tipo de cuenta que creaste para el adaptador de sincronización, declaran una autoridad de proveedor de contenido asociada con la app, controlan una parte de la interfaz de usuario del sistema relacionada con los adaptadores de sincronización y declaran otras marcas relacionadas con la sincronización. Declara los metadatos en un archivo XML especial almacenado en el directorio /res/xml/ del proyecto de la app. Puedes darle cualquier nombre al archivo, aunque por lo general se llama syncadapter.xml.
El archivo XML contiene un solo elemento XML <sync-adapter> que tiene los siguientes atributos:
android:contentAuthority- La autoridad del URI para tu proveedor de contenido. Si creaste un proveedor de contenido de stub para la app en la lección anterior Cómo crear un proveedor de contenido de stub, usa el valor del atributo
android:authoritiesespecificado en el elemento<provider>que agregaste al manifiesto de la aplicación. El atributo se describe con más detalle en la sección Cómo declarar el proveedor en el manifiesto.
Si transfieres datos de un proveedor de contenido a un servidor con el adaptador de sincronización, el valor debe ser igual a la autoridad del URI de contenido que usas para esos datos. El valor también es una de las autoridades que especificas en el atributoandroid:authoritiesdel elemento<provider>que declara tu proveedor en el manifiesto de la app. android:accountType- El tipo de cuenta requerido por el framework del adaptador de sincronización. El valor debe ser igual que el valor del tipo de cuenta que proporcionaste cuando creaste el archivo de metadatos del autenticador, como se describe en la sección Cómo agregar el archivo de metadatos del autenticador. También es el valor de la constante
ACCOUNT_TYPEespecificado en el fragmento de código de la sección Cómo agregar la cuenta obligatoria para el framework. - Atributos de configuración
-
-
android:userVisible - Establece la visibilidad del tipo de cuenta del adaptador de sincronización. De forma predeterminada, el ícono y la etiqueta de la cuenta asociados al tipo de cuenta se muestran en la sección Cuentas de la app de Configuración del sistema, por lo que debes inhabilitar tu adaptador de sincronización, a menos que tengas un dominio o tipo de cuenta asociados a tu app. Si haces invisible el tipo de cuenta, igual puedes permitir que los usuarios controlen el adaptador de sincronización con una interfaz de usuario en una de las actividades de tu app.
-
android:supportsUploading - Te permite subir datos a la nube. Establece el atributo como
falsesi la app solo descarga datos. -
android:allowParallelSyncs - Permite que se ejecuten al mismo tiempo varias instancias del componente de adaptador de sincronización. Úsalo si la app admite varias cuentas de usuario y quieres permitir que varios usuarios transfieran datos en paralelo. La marca no funciona si nunca ejecutas múltiples transferencias de datos.
-
android:isAlwaysSyncable - Indica al framework del adaptador de sincronización que puede ejecutar el adaptador en cualquier momento que hayas especificado. Si quieres controlar de manera programática cuándo se puede ejecutar el adaptador de sincronización, establece la marca como
falsey, luego, llama arequestSync()para ejecutar el adaptador de sincronización. Para obtener más información sobre cómo ejecutar un adaptador de sincronización, consulta la lección Cómo ejecutar un adaptador de sincronización.
-
En el siguiente ejemplo, se muestra el XML de un adaptador de sincronización que usa una sola cuenta ficticia y solo realiza descargas.
<?xml version="1.0" encoding="utf-8"?>
<sync-adapter
xmlns:android="http://schemas.android.com/apk/res/android"
android:contentAuthority="com.example.android.datasync.provider"
android:accountType="com.android.example.datasync"
android:userVisible="false"
android:supportsUploading="false"
android:allowParallelSyncs="false"
android:isAlwaysSyncable="true"/>
Cómo declarar el adaptador de sincronización en el manifiesto
Una vez que hayas agregado el componente del adaptador de sincronización a la app, deberás solicitar permisos relacionados con el uso del componente y declarar el Service vinculado que agregaste.
Debido a que el componente del adaptador de sincronización ejecuta un código que transfiere datos entre la red y el dispositivo, debes solicitar permiso para acceder a Internet. Además, la app debe solicitar permiso para leer y escribir la configuración del adaptador de sincronización, de manera que puedas controlar el adaptador de sincronización de manera programática desde otros componentes de la app. También debes solicitar un permiso especial para que la app use el componente de autenticación creado en la lección Cómo crear un autenticador de stub.
Para solicitar los permisos, agrega lo siguiente al manifiesto de la app como elementos secundarios de <manifest>:
-
android.permission.INTERNET - Permite que el código del adaptador de sincronización acceda a Internet para descargar o subir datos entre el dispositivo y un servidor. No necesitas volver a agregar este permiso si ya lo solicitaste.
-
android.permission.READ_SYNC_SETTINGS - Permite que tu app lea la configuración actual del adaptador de sincronización. Por ejemplo, necesitas el permiso para llamar a
getIsSyncable(). -
android.permission.WRITE_SYNC_SETTINGS - Permite que tu app controle la configuración del adaptador de sincronización. Necesitas el permiso para configurar ejecuciones periódicas del adaptador de sincronización con
addPeriodicSync(). Este permiso no es obligatorio para llamar arequestSync(). Para obtener más información sobre cómo ejecutar el adaptador de sincronización, consulta Cómo ejecutar un adaptador de sincronización.
En el siguiente fragmento, se muestra cómo agregar los permisos:
<manifest>
...
<uses-permission
android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.READ_SYNC_SETTINGS"/>
<uses-permission
android:name="android.permission.WRITE_SYNC_SETTINGS"/>
<uses-permission
android:name="android.permission.AUTHENTICATE_ACCOUNTS"/>
...
</manifest>
Por último, a fin de declarar el Service vinculado que el framework usa para interactuar con el adaptador de sincronización, agrega el siguiente XML al manifiesto de la app como un elemento secundario de <application>:
<service
android:name="com.example.android.datasync.SyncService"
android:exported="true"
android:process=":sync">
<intent-filter>
<action android:name="android.content.SyncAdapter"/>
</intent-filter>
<meta-data android:name="android.content.SyncAdapter"
android:resource="@xml/syncadapter" />
</service>
El elemento <intent-filter> configura un filtro que se activa mediante la acción de intent android.content.SyncAdapter, enviada por el sistema para ejecutar el adaptador de sincronización. Cuando se activa el filtro, el sistema inicia el servicio vinculado que creaste, que en este ejemplo es SyncService. El atributo android:exported="true" permite que otros procesos distintos que la app (incluido el sistema) accedan a Service. El atributo android:process=":sync" le indica al sistema que ejecute Service en un proceso compartido global llamado sync. Si tienes múltiples adaptadores de sincronización en la app, pueden compartir el proceso, lo que reduce la sobrecarga.
El elemento <meta-data> proporciona el nombre del archivo XML de metadatos del adaptador de sincronización que creaste antes.
El atributo android:name indica que los metadatos son para el framework del adaptador de sincronización. El elemento android:resource especifica el nombre del archivo de metadatos.
Ahora tienes todos los componentes para el adaptador de sincronización. En la siguiente lección, se muestra cómo indicarle al framework del adaptador de sincronización que ejecute el adaptador, ya sea en respuesta a un evento o en un programa habitual.