src/com/android/contacts/util/NameConverter.java

/*
 * Copyright (C) 2011 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 com.android.contacts.util;


import android.content.ContentValues;
import android.content.Context;
import android.database.Cursor;
import android.net.Uri;
import android.net.Uri.Builder;
import android.provider.ContactsContract;
import android.provider.ContactsContract.CommonDataKinds.StructuredName;
import android.text.TextUtils;

import java.util.Map;
import java.util.TreeMap;

/**
 * Utility class for converting between a display name and structured name (and vice-versa), via
 * calls to the contact provider.
 */
public class NameConverter {

    /**
     * The array of fields that comprise a structured name.
     */
    public static final String[] STRUCTURED_NAME_FIELDS = new String[] {
            StructuredName.PREFIX,
            StructuredName.GIVEN_NAME,
            StructuredName.MIDDLE_NAME,
            StructuredName.FAMILY_NAME,
            StructuredName.SUFFIX
    };

    /**
     * Converts the given structured name (provided as a map from {@link StructuredName} fields to
     * corresponding values) into a display name string.
     * <p>
     * Note that this operates via a call back to the ContactProvider, but it does not access the
     * database, so it should be safe to call from the UI thread.  See
     * ContactsProvider2.completeName() for the underlying method call.
     * @param context Activity context.
     * @param structuredName The structured name map to convert.
     * @return The display name computed from the structured name map.
     */
    public static String structuredNameToDisplayName(Context context,
            Map<String, String> structuredName) {
        Builder builder = ContactsContract.AUTHORITY_URI.buildUpon().appendPath("complete_name");
        for (String key : STRUCTURED_NAME_FIELDS) {
            if (structuredName.containsKey(key)) {
                appendQueryParameter(builder, key, structuredName.get(key));
            }
        }
        return fetchDisplayName(context, builder.build());
    }

    /**
     * Converts the given structured name (provided as ContentValues) into a display name string.
     * @param context Activity context.
     * @param values The content values containing values comprising the structured name.
     * @return
     */
    public static String structuredNameToDisplayName(Context context, ContentValues values) {
        Builder builder = ContactsContract.AUTHORITY_URI.buildUpon().appendPath("complete_name");
        for (String key : STRUCTURED_NAME_FIELDS) {
            if (values.containsKey(key)) {
                appendQueryParameter(builder, key, values.getAsString(key));
            }
        }
        return fetchDisplayName(context, builder.build());
    }

    /**
     * Helper method for fetching the display name via the given URI.
     */
    private static String fetchDisplayName(Context context, Uri uri) {
        String displayName = null;
        Cursor cursor = context.getContentResolver().query(uri, new String[]{
                StructuredName.DISPLAY_NAME,
        }, null, null, null);

        try {
            if (cursor.moveToFirst()) {
                displayName = cursor.getString(0);
            }
        } finally {
            cursor.close();
        }
        return displayName;
    }

    /**
     * Converts the given display name string into a structured name (as a map from
     * {@link StructuredName} fields to corresponding values).
     * <p>
     * Note that this operates via a call back to the ContactProvider, but it does not access the
     * database, so it should be safe to call from the UI thread.
     * @param context Activity context.
     * @param displayName The display name to convert.
     * @return The structured name map computed from the display name.
     */
    public static Map<String, String> displayNameToStructuredName(Context context,
            String displayName) {
        Map<String, String> structuredName = new TreeMap<String, String>();
        Builder builder = ContactsContract.AUTHORITY_URI.buildUpon().appendPath("complete_name");

        appendQueryParameter(builder, StructuredName.DISPLAY_NAME, displayName);
        Cursor cursor = context.getContentResolver().query(builder.build(), STRUCTURED_NAME_FIELDS,
                null, null, null);

        try {
            if (cursor.moveToFirst()) {
                for (int i = 0; i < STRUCTURED_NAME_FIELDS.length; i++) {
                    structuredName.put(STRUCTURED_NAME_FIELDS[i], cursor.getString(i));
                }
            }
        } finally {
            cursor.close();
        }
        return structuredName;
    }

    /**
     * Converts the given display name string into a structured name (inserting the structured
     * values into a new or existing ContentValues object).
     * <p>
     * Note that this operates via a call back to the ContactProvider, but it does not access the
     * database, so it should be safe to call from the UI thread.
     * @param context Activity context.
     * @param displayName The display name to convert.
     * @param contentValues The content values object to place the structured name values into.  If
     *     null, a new one will be created and returned.
     * @return The ContentValues object containing the structured name fields derived from the
     *     display name.
     */
    public static ContentValues displayNameToStructuredName(Context context, String displayName,
            ContentValues contentValues) {
        if (contentValues == null) {
            contentValues = new ContentValues();
        }
        Map<String, String> mapValues = displayNameToStructuredName(context, displayName);
        for (String key : mapValues.keySet()) {
            contentValues.put(key, mapValues.get(key));
        }
        return contentValues;
    }

    private static void appendQueryParameter(Builder builder, String field, String value) {
        if (!TextUtils.isEmpty(value)) {
            builder.appendQueryParameter(field, value);
        }
    }
}