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
17package android.content;
18
19import 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*       &quot;directories&quot; although they do not refer to file directories. The right-most
56*       segment in a path is often called a &quot;twig&quot;
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*/
70public 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     */
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     */
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     */
109    public static Uri withAppendedId(Uri contentUri, long id) {
110        return appendId(contentUri.buildUpon(), id).build();
111    }
112}
113