1 /* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.content; 18 19 import android.net.Uri; 20 21 /** 22 * Utility methods useful for working with {@link android.net.Uri} objects 23 * that use the "content" (content://) scheme. 24 * 25 *<p> 26 * Content URIs have the syntax 27 *</p> 28 *<p> 29 * <code>content://<em>authority</em>/<em>path</em>/<em>id</em></code> 30 *</p> 31 *<dl> 32 * <dt> 33 * <code>content:</code> 34 * </dt> 35 * <dd> 36 * The scheme portion of the URI. This is always set to {@link 37 * android.content.ContentResolver#SCHEME_CONTENT ContentResolver.SCHEME_CONTENT} (value 38 * <code>content://</code>). 39 * </dd> 40 * <dt> 41 * <em>authority</em> 42 * </dt> 43 * <dd> 44 * A string that identifies the entire content provider. All the content URIs for the provider 45 * start with this string. To guarantee a unique authority, providers should consider 46 * using an authority that is the same as the provider class' package identifier. 47 * </dd> 48 * <dt> 49 * <em>path</em> 50 * </dt> 51 * <dd> 52 * Zero or more segments, separated by a forward slash (<code>/</code>), that identify 53 * some subset of the provider's data. Most providers use the path part to identify 54 * individual tables. Individual segments in the path are often called 55 * "directories" although they do not refer to file directories. The right-most 56 * segment in a path is often called a "twig" 57 * </dd> 58 * <dt> 59 * <em>id</em> 60 * </dt> 61 * <dd> 62 * A unique numeric identifier for a single row in the subset of data identified by the 63 * preceding path part. Most providers recognize content URIs that contain an id part 64 * and give them special handling. A table that contains a column named <code>_ID</code> 65 * often expects the id part to be a particular value for that column. 66 * </dd> 67 *</dl> 68 * 69 */ 70 public class ContentUris { 71 72 /** 73 * Converts the last path segment to a long. 74 * 75 * <p>This supports a common convention for content URIs where an ID is 76 * stored in the last segment. 77 * 78 * @throws UnsupportedOperationException if this isn't a hierarchical URI 79 * @throws NumberFormatException if the last segment isn't a number 80 * 81 * @return the long conversion of the last segment or -1 if the path is 82 * empty 83 */ parseId(Uri contentUri)84 public static long parseId(Uri contentUri) { 85 String last = contentUri.getLastPathSegment(); 86 return last == null ? -1 : Long.parseLong(last); 87 } 88 89 /** 90 * Appends the given ID to the end of the path. 91 * 92 * @param builder to append the ID to 93 * @param id to append 94 * 95 * @return the given builder 96 */ appendId(Uri.Builder builder, long id)97 public static Uri.Builder appendId(Uri.Builder builder, long id) { 98 return builder.appendEncodedPath(String.valueOf(id)); 99 } 100 101 /** 102 * Appends the given ID to the end of the path. 103 * 104 * @param contentUri to start with 105 * @param id to append 106 * 107 * @return a new URI with the given ID appended to the end of the path 108 */ withAppendedId(Uri contentUri, long id)109 public static Uri withAppendedId(Uri contentUri, long id) { 110 return appendId(contentUri.buildUpon(), id).build(); 111 } 112 } 113