A library of classes to facilitate the creating of table-based content providers. Applications may use these classes to create a content provider with the minimum amount of code, while still retaining reasonable flexibility to implement custom behaviour.

Simple Usage

The basic usage model is this:

For a simple provider, it's really that easy. All of the code for managing the database, and doing inserts, queries, etc., is provided for you.

Handling Database Upgrade

The default implementation handles database upgrade by simply deleting the existing database, and creating a fresh one. This is something that many applications will wish to improve on, and you can do this by providing a custom subclass of {@link org.hermit.android.provider.DatabaseHelper}.

To do this, first create your helper subclass. Override {@link org.hermit.android.provider.DatabaseHelper#onUpgrade(SQLiteDatabase, int, int)} and any other methods you need. Then, in your {@link org.hermit.android.provider.TableProvider} subclass, override {@link org.hermit.android.provider.TableProvider#getHelper()} to return an instance of your database helper.

Example

The following example illustrates a very simple provider, which is the basis for an app logging broadcast events.

First, the schema definition:

package org.hermit.broadtest.provider;

import org.hermit.android.provider.DbSchema;
import org.hermit.android.provider.TableSchema;

import android.net.Uri;

/**
 * Class encapsulating the schema for the broadcast content provider.
 */
public class BroadcastSchema
    extends DbSchema
{

    private static final String DATABASE_NAME = "broadcasts";

    // Current schema version.
    private static final int SCHEMA_VERSION = 2;
    
    // Provider authority name.
    private static final String AUTHORITY = "com.bn.provider.Broadcast";

    public static final class BroadcastTable
        extends TableSchema
    {
        
        // Name of the broadcasts table.
        private static final String TABLE_NAME = "broadcasts";

        // Base MIME type for the broadcasts table.
        private static final String TABLE_TYPE = "vnd.bn.broadcast";
        
        /**
         * The content:// style URL for the broadcasts table.
         */
        public static final Uri CONTENT_URI =
                        Uri.parse("content://" + AUTHORITY + "/broadcasts");

        /**
         * The default sort order for the broadcasts table.
         */
        public static final String SORT_ORDER = "time DESC";

        /**
         * Broadcast table field: the title of the broadcast.
         */
        public static final String TITLE = "title";

        /**
         * Broadcast table field: any extras that came with the broadcast.
         */
        public static final String EXTRAS = "extras";

        /**
         * Broadcast table field: the timestamp for when the broadcast was
         * received.
         */
        public static final String TIME = "time";

        // Definitions of the fields.
        private static final String[][] FIELDS = {
            { TITLE, "TEXT" },
            { EXTRAS, "TEXT" },
            { TIME, "INTEGER" },
        };

        /**
         * A default projection which gets all the fields of the broadcast
         * table.
         */
        public static final String[] PROJECTION = makeProjection(FIELDS);
        
        /**
         * Create a broadcasts table schema instance.
         */
        protected BroadcastTable() {
            super(TABLE_NAME, TABLE_TYPE, CONTENT_URI, SORT_ORDER, FIELDS);
        }

    }

    /**
     * Create a broadcast database schema instance.
     */
    protected BroadcastSchema() {
        super(DATABASE_NAME, SCHEMA_VERSION, AUTHORITY, TABLE_SCHEMAS);
    }

    // Our table schemas.
    private static final TableSchema[] TABLE_SCHEMAS = {
        new BroadcastTable(),
    };
    
}

With that, the provider itself is trivial:

package org.hermit.broadtest.provider;

import org.hermit.android.provider.TableProvider;

/**
 * Content provider for stored broadcast events.
 */
public class BroadcastProvider
    extends TableProvider
{

    /**
     * Create an instance of this content provider.
     */
    public BroadcastProvider() {
        super(new BroadcastSchema());
    }
    
}

And finally, the manifest:

        <provider android:name=".provider.BroadcastProvider"
            android:authorities="com.bn.provider.Broadcast" />