[Android] ContentProvider 문서 읽기

 

https://developer.android.com/reference/android/content/ContentProvider

ContentProvider  |  Android Developers

 

public abstract class ContentProvider extends Object implements ComponentCallbacks2

 

콘텐츠 프로바이더는 안드로이드 애플리케이션들 중에 중요 구성요소들 중 하나로, 애플리케이션들에 콘텐츠를 제공합니다. 콘텐츠 프로바이더는 데이터를 캡슐화하고 단일 ContentResolver 인터페이스를 통해 애플리케이션들에 이것을 제공합니다. 콘텐츠 프로바이더는 여러 애플리케이션들 사이에서 데이터를 공유해야할 때만 필요합니다. 예를 들어, 연락처 데이터는 여러 앱들에서 사용되고, 콘텐츠 프로바이더 안에서 저장되어야만 합니다. 만약 여러 애플리케이션들 사이에서 데이터를 공유할 필요가 없다면 SQLiteDatabase를 통해 직접적으로 데이터베이스를 사용할 수 있습니다.

 

요청(request)은 ContentResolver를 통해서 만들어지고, 시스템은 주어진 URI의 권한을 점검하고 요청을 권한을 가진 등록된 콘텐트 프로바이더로 보냅니다. 콘텐츠 프로바이더는 URI의 나머지 부분을 원하는 대로 해석할 수 있습니다. UriMatcher 클래스는 URI 파싱을 도와주죠.

 

구현되어야 하는 주요 메소드들입니다.

• onCreate() : 프로바이더를 초기화하는데 호출됩니다. 
• query(Uri, String[], Bundel, CancellationSignal) : 호출자에게 데이터를 반환합니다.
• insert(Uri, ContentValues) : 컨텐츠 프로바이더로 새 데이터를 삽입합니다.
• update(Uri, ContentValues, Bundle) : 콘텐츠 프로바이더 안의 존재하는 데이터를 업데이트합니다.
• delete(Uri, Bundle) : 콘텐츠 프로바이더의 데이터를 삭제합니다.
• getType(Uri) : 콘텐츠 프로바이더 안의 데이터의 MIME 타입을 반환합니다.

 

❗

(insert(Uri, ContentValues), update(Uri,ContentValues, Bundle)과 같은) 데이터 접근 메소드들은 한번에 많은 쓰레들에서 호출될 수 있고, 반드시 thread-safe해야만 합니다. (onCreate() 같은) 다른 메소드들은 애플리케이션의 메인 쓰레드에서만 호출되고, 너무 긴 작업을 수행하는 것은 반드시 피해야만합니다. 예상되는 쓰레드 동작들은 메소드 설명들을 보세요.

 

ContentResolver로의 요청들은 자동으로 적절한 콘텐츠 프로바이더 인스턴스에 전달되고, 하위 클래스들은 프로세스 간의 호출들의 상세한 것들에 대해서는 걱정할 필요가 없습니다.

 

onCreate

public abstract boolean onCreate()

 

스타트업 때에 컨텐츠 프로바이더를 초기화하기 위해 구현하세요. 이 메서드는 애플리케이션의 시작(launch) 시간에 애플리케이션의 메인 쓰레드에서 모든 등록된 콘텐츠 프로바이더들을 호출됩니다. 너무 긴 작업을 수행하면 안됩니다. 그렇게 한다면 스타트업이 지연됩니다.

 

콘텐츠 프로바이더가 (query(Uri, String[], Bundle, CancellationSignal), insert(Uri, ContentValues)등을 통해) 사용되기 전까지 (데이터베이스를 열거나, 업그레이드 하거나, 스캔하는 것처럼 ) 중요하지 않은 초기화는 연기해야 합니다. 지연된 초기화는 애플리케이션의 스타트업을 빠르게 유지하고, 프로바이더가 불필요하다면 불필요한 작업을 피하고, (full disk와 같은) 데이터베이스 에러가 앱 실행을 중지시키는 것을 막습니다 . 

 

SQLite를 사용한다면, SQLiteOpenHelper는 데이터베이스를 쉽게 관리하도록 하고 처음 사용할 때까지 자동으로 실행을 지연시키는데 도움이 되는 유틸리티 클래스입니다. 만약 SQLiteOpenHelper를 사용한다면, 이 메서드에서 SQLiteOpenHelper.getReadableDatabase() 또는 SQLiteOpenHelper.getWritableDatabase()를 호출하는 건 피해야만 합니다. (대신에, 처음 오픈될 때 데이터베이스를 초기화하려면 SQLiteOpenHelper.onOpen(SQLiteDatabase)를 오버라이드하세요.)

 

query

1

public Cursor query (Uri uri, String[] projection, Bundel queryArgs, 
                                          CancellationSignal cacellationSignal)

Bundle 안에 들어가는 인수들의 쿼리 요청을 처리하려면 이것을 구현하세요. 인수들은 전통적인 SQL 스타일의 쿼리 인수들으 포함할 겁니다. 존재할 때에 query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String, android.os.CancellationSignal)에 성립된 제약에 따라 처리되어야 합니다. 

 

전통적인 SQL 인수들은 번들 안에서 다음의 키로 표현될 수 있습니다.

• ContentResolver.QUERY_ARG_SQL_SELECTION
• ContentResolver.QUERY_ARG_SQL_SELECTION_ARGS
• ContentResolver.QUERY_ARG_SQL_SORT_ORDER

Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

클라이언트 호출 예: 

//  인덱스가 30인 행에서 시작해 20개의 레코드를 요청합니다.
Bundle queryArgs = new Bundle();
queryArgs.putInt(ContentResolver.QUERY_ARG_OFFSET, 30);
queryArgs.putInt(ContentResolver.QUERY_ARG_LIMIT, 20);

Cursor cursor = getContentReslver().query(
        contentUri,    // Content Uri는 개별 콘텐츠 프로바이더에 따라 다릅니다.
        projection,    // String[] 은 반환할 열이 어떤 것인지 기술합니다.
        queryArgs,     // 쿼리 인자들
        null);         // 취소(cancellation) signal.

구현 예시 :

int recordsetSize = 0x1000;  //  실제 값은 구현에 따라 다릅니다.
queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY;  // queryArgs가 non-null임을
                                                           // 확실히 합니다.
                                                           
int offset = queryArgs.getInt(ContentResolver.QUERY_ARG_OFFSET, 0);
int limit = queryArgs.getInt(ContentResolve.QUERY_ARG_LIMIT, Integer.MIN_VALUE);

MatrixCursor c = new MatrixCursor(PROJECTION, limit);

// 커서 안에 들어가는 아이템의 숫자를 계산합니다.
int numItems = MathUtils.constrain(recordsetSize - offset, 0, limit);

// 페이지 수를 매긴 결과 집합을 빌드합니다.
for (int i = offset; i < offset + numItems; i++) {
    // 데이터로부터 행을 채웁니다.
}

Bundle extras = new Bundle();
c.setExtras(extras);

// 지정된다면(if honored. 중요하다고 인정받는다면) 어떠한 QUERY_ARG_* 키든 포함될 수 있습니다.
// 실제 구현에서, queryArgs 안에 표현되고 Cursor 출력에도 표현되는 두 가지를 만족하는 키들만
// 포함시키세요. 만약 QUERY_ARG_OFFSET이 queryArgs 안에 포함되었어도 (-273과 같은) 유효하지
// 않은 값을 포함하고 있기 때문에 무시될 것이고, QUERY_ARG_OFFSET은 생략되어야만 합니다.
extras.putStringArray(ContentResolver.EXTRA_HONORED_ARGS, new String[]{
    ContentResolver.QUERY_ARG_OFFSET,
    ContentResolver.QUERY_ARG_LIMIT
});

extras.putInt(ContentResolover.EXTRA_TOTAL_COUNT, recordsetSize);

cursor.setNotificationUri(getContext().getContentResolver(), uri);

return cursor;

자세한 구현은 query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String, android.os.CancellationSignal)을 보세요.

 

2

public Cursor query(Uri uri, String[] projection, String, selection, Strign[] selectionArgs, 
                                       Strign sortOrder, CancellationSignal cancellationSignal)

취소를 지원하는 클라이언트의 쿼리 요청을 처리하려면 이것을 구현하세요.

 

Build.VERSION_CODES_O 이상을 타게팅하는 앱들은 이 메서드 대신에 query(android.net.Uri, java.lang.String[], android.os.Bundle, android.os.CancellationSignal)을 오버라이드하세요.

 

Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

클라이언트 호출 예:

// 특정 레코드를 요청합니다.
Cursor managedCursor = managedQuery(
        ContentUris.withAppendedId(Contract.People.CONTENT_URI, 2),
        projection,  // 반환하는 열이 어떤 열인지
        null,        // WHERE 절(clause. 문구)
        null,        // WHERE 절 값의 대체
        People.NAME + " ASC");  // 정렬 순서

구현 예:

// SQLiteAueryBuilder는 적절한 SQL 구문을 생성하는 것을 도와주는 클래스 입니다.
SQLIteQueryBuilder qBuilder = new SQLiteQueryBuilder();

// 우리가 쿼리를 진행할 테이블을 설정합니다.
qBuilder.setTables(DATABASE_TABEL_NAME);

// 만약 특정 레코드 숫자에서 쿼리가 끝난다면, 우리는 특정 레코드에 대한 요청을 받을 것이고, 
// 쿼리 안에 WHERE 절을 설정합니다.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE) {
    qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}

// 쿼리를 만들어 줍니다.
Cursor c = qBuilde.query(mDb,
        projection,
        selection,
        selectionArgs,
        groupBy,
        having,
        sortOrder);
c.setNotificationUri(getCotext().getContentResolver(), uri);
return c;

만약 이 메서드를 구현한다면, 취소 신호 오버로드가 불가능한 옛 버전의 안드로이드 프레임워크에서 정확한 작업 수행을 확실하게 하기 위해서 취소 신호를 받지 않는 query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String)의 버전도 반드시 구현해야합니다.

 

3

public abstract Cursor query(Uri uri,Sring[] projection, String selection, 
                                                String[] selectionArgs, String sortOrder)

클라이언트에서 쿼리 요청을 처리하기 위해서 이것을 구현하세요.

Build.VERSION_CODES.O 이상을 타게팅하는 앱들은 query(android.net.Uri, java.lang.String[], android.os.Bundle, android.os.CancellationSignal)을 오버라이드 해야하고, 이 메서드의 구현의 일부분을 제공해야 합니다.

 

Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

클라이언트 호출 예:

// 특정 레코드를 요청합니다.
Cursor managedCursor = managedQuery(
        ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
        projection,  // 반환될 행이 어떤 것인지
        null,        // WHERE 절
        null,        // WHERE 절 값 대체
        People.NAME + " ASC");  // 정렬 순서

구현 예:

// SQLiteAueryBuilder는 적절한 SQL 구문을 생성하는 것을 도와주는 클래스 입니다.
SQLIteQueryBuilder qBuilder = new SQLiteQueryBuilder();

// 우리가 쿼리를 진행할 테이블을 설정합니다.
qBuilder.setTables(DATABASE_TABEL_NAME);

// 만약 특정 레코드 숫자에서 쿼리가 끝난다면, 우리는 특정 레코드에 대한 요청을 받을 것이고, 
// 쿼리 안에 WHERE 절을 설정합니다.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE) {
    qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}

// 쿼리를 만들어 줍니다.
Cursor c = qBuilde.query(mDb,
        projection,
        selection,
        selectionArgs,
        groupBy,
        having,
        sortOrder);
c.setNotificationUri(getCotext().getContentResolver(), uri);
return c;

 

insert

public Uri insert (Uri uri, ContentValues values, Bundle extras)
public abstract Uri insert(Uri uri,ConentValues values)

새로운 행 하나를 삽입하는 요청을 처리하려면 이것을 구현하세요. 의례적으로, 삽입 후에는 notifyChanged()를 호출하세요. Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

update

public int update (Uri uri, ContentValues values, Bundel extras)
public int update (Uri uri, ContentValues values, String selection, String[] selectionArgs)

하나 이상의 행들(rows)을 업데이트 하는 요청들을 처리하려면 이것을 구현하세요. 이 구현은 제공된 값을의 map에 따라  열들(columns)을 설정하기 위해 선택(selection)과 일치하는 모든 행들을 업데이트해야 합니다. 의례적으로, 업데이트 후에는 notifyChange()를 호출하세요. Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

delete

public abstract int delete (Uri uri, String selection, String[] selectionArgs)
public int delete (Uri uri, Bundel extra)

하나 이상의 행들(rows)을 삭제하는 요청들을 처리하려면 이것을 구현하세요. 이 구현은 삭제 작업을 할 때에  선택 조항(selection clause)을 적용해 그 작업이 한 디렉터리 안에서 여러 행들이 영향을 주도록 해야 합니다. 의례적으로, 삭제 후에는 notifyChanged()를 호출하세요. Processes and Threads에서 기술된 바와 같이, 이 메서드는 여러 쓰레드에서 호출 가능합니다.

 

이 구현은 특성 행이 삭제되는 경우에 URI 끝의 행 ID를 파싱할 책입이 있습니다. 즉, 클라이언트가 contnet://contacts/people.22를 보내고 구현은 SQL 구문을 생성할 때에 레코드 숫자(22)를 파싱할 책입이 있죠.

 

getType

public abstract String getType (Uri uri)

주어진 URI에서 데이터의 MIME 타입에 대한 요청을 처리하려면 이것을 구현하세요. 반환된 MIME 타입은 단일 레코드의 경우 vnd.android.cursor.item으로 시작하거나, 여러 항목들인 경우에 vnd.android.cursor.dir/로 시작해야합니다. 이 메소드는 Processes and Threads 에서 기술된 대로, 여러 쓰레드에서 호출할 수 있습니다.

 

애플리케이션이 이 정보(MIME 타입)에 접근하는데 필요한 권한은 없습니다. 만약 콘텐츠 프로바이더가 읽기 그리고/또는 쓰기 권한들이 필요하거나, 콘텐츠 프로바이더가 exported 되지 않는다면, 모든 애플리케이션들은 접근 권한과 상관없이 이 메소드를 계속 호출할 수 있습니다. 이렇게 인텐트들이 발송될 때 URI의 MIME 타입을 검색할 수 있습니다.