1 /*
2  * Copyright (C) 2006 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 import java.util.ArrayList;
22 import java.util.List;
23 import java.util.regex.Pattern;
24 
25 /**
26 Utility class to aid in matching URIs in content providers.
27 
28 <p>To use this class, build up a tree of <code>UriMatcher</code> objects.
29 For example:
30 <pre>
31     private static final int PEOPLE = 1;
32     private static final int PEOPLE_ID = 2;
33     private static final int PEOPLE_PHONES = 3;
34     private static final int PEOPLE_PHONES_ID = 4;
35     private static final int PEOPLE_CONTACTMETHODS = 7;
36     private static final int PEOPLE_CONTACTMETHODS_ID = 8;
37 
38     private static final int DELETED_PEOPLE = 20;
39 
40     private static final int PHONES = 9;
41     private static final int PHONES_ID = 10;
42     private static final int PHONES_FILTER = 14;
43 
44     private static final int CONTACTMETHODS = 18;
45     private static final int CONTACTMETHODS_ID = 19;
46 
47     private static final int CALLS = 11;
48     private static final int CALLS_ID = 12;
49     private static final int CALLS_FILTER = 15;
50 
51     private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH);
52 
53     static
54     {
55         sURIMatcher.addURI("contacts", "people", PEOPLE);
56         sURIMatcher.addURI("contacts", "people/#", PEOPLE_ID);
57         sURIMatcher.addURI("contacts", "people/#/phones", PEOPLE_PHONES);
58         sURIMatcher.addURI("contacts", "people/#/phones/#", PEOPLE_PHONES_ID);
59         sURIMatcher.addURI("contacts", "people/#/contact_methods", PEOPLE_CONTACTMETHODS);
60         sURIMatcher.addURI("contacts", "people/#/contact_methods/#", PEOPLE_CONTACTMETHODS_ID);
61         sURIMatcher.addURI("contacts", "deleted_people", DELETED_PEOPLE);
62         sURIMatcher.addURI("contacts", "phones", PHONES);
63         sURIMatcher.addURI("contacts", "phones/filter/*", PHONES_FILTER);
64         sURIMatcher.addURI("contacts", "phones/#", PHONES_ID);
65         sURIMatcher.addURI("contacts", "contact_methods", CONTACTMETHODS);
66         sURIMatcher.addURI("contacts", "contact_methods/#", CONTACTMETHODS_ID);
67         sURIMatcher.addURI("call_log", "calls", CALLS);
68         sURIMatcher.addURI("call_log", "calls/filter/*", CALLS_FILTER);
69         sURIMatcher.addURI("call_log", "calls/#", CALLS_ID);
70     }
71 </pre>
72 <p>Starting from API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}, paths can start
73  with a leading slash.  For example:
74 <pre>
75         sURIMatcher.addURI("contacts", "/people", PEOPLE);
76 </pre>
77 <p>Then when you need to match against a URI, call {@link #match}, providing
78 the URL that you have been given.  You can use the result to build a query,
79 return a type, insert or delete a row, or whatever you need, without duplicating
80 all of the if-else logic that you would otherwise need.  For example:
81 <pre>
82     public String getType(Uri url)
83     {
84         int match = sURIMatcher.match(url);
85         switch (match)
86         {
87             case PEOPLE:
88                 return "vnd.android.cursor.dir/person";
89             case PEOPLE_ID:
90                 return "vnd.android.cursor.item/person";
91 ... snip ...
92                 return "vnd.android.cursor.dir/snail-mail";
93             case PEOPLE_ADDRESS_ID:
94                 return "vnd.android.cursor.item/snail-mail";
95             default:
96                 return null;
97         }
98     }
99 </pre>
100 instead of:
101 <pre>
102     public String getType(Uri url)
103     {
104         List<String> pathSegments = url.getPathSegments();
105         if (pathSegments.size() >= 2) {
106             if ("people".equals(pathSegments.get(1))) {
107                 if (pathSegments.size() == 2) {
108                     return "vnd.android.cursor.dir/person";
109                 } else if (pathSegments.size() == 3) {
110                     return "vnd.android.cursor.item/person";
111 ... snip ...
112                     return "vnd.android.cursor.dir/snail-mail";
113                 } else if (pathSegments.size() == 3) {
114                     return "vnd.android.cursor.item/snail-mail";
115                 }
116             }
117         }
118         return null;
119     }
120 </pre>
121 */
122 public class UriMatcher
123 {
124     public static final int NO_MATCH = -1;
125     /**
126      * Creates the root node of the URI tree.
127      *
128      * @param code the code to match for the root URI
129      */
UriMatcher(int code)130     public UriMatcher(int code)
131     {
132         mCode = code;
133         mWhich = -1;
134         mChildren = new ArrayList<UriMatcher>();
135         mText = null;
136     }
137 
UriMatcher()138     private UriMatcher()
139     {
140         mCode = NO_MATCH;
141         mWhich = -1;
142         mChildren = new ArrayList<UriMatcher>();
143         mText = null;
144     }
145 
146     /**
147      * Add a URI to match, and the code to return when this URI is
148      * matched. URI nodes may be exact match string, the token "*"
149      * that matches any text, or the token "#" that matches only
150      * numbers.
151      * <p>
152      * Starting from API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2},
153      * this method will accept a leading slash in the path.
154      *
155      * @param authority the authority to match
156      * @param path the path to match. * may be used as a wild card for
157      * any text, and # may be used as a wild card for numbers.
158      * @param code the code that is returned when a URI is matched
159      * against the given components. Must be positive.
160      */
addURI(String authority, String path, int code)161     public void addURI(String authority, String path, int code)
162     {
163         if (code < 0) {
164             throw new IllegalArgumentException("code " + code + " is invalid: it must be positive");
165         }
166 
167         String[] tokens = null;
168         if (path != null) {
169             String newPath = path;
170             // Strip leading slash if present.
171             if (path.length() > 0 && path.charAt(0) == '/') {
172                 newPath = path.substring(1);
173             }
174             tokens = PATH_SPLIT_PATTERN.split(newPath);
175         }
176 
177         int numTokens = tokens != null ? tokens.length : 0;
178         UriMatcher node = this;
179         for (int i = -1; i < numTokens; i++) {
180             String token = i < 0 ? authority : tokens[i];
181             ArrayList<UriMatcher> children = node.mChildren;
182             int numChildren = children.size();
183             UriMatcher child;
184             int j;
185             for (j = 0; j < numChildren; j++) {
186                 child = children.get(j);
187                 if (token.equals(child.mText)) {
188                     node = child;
189                     break;
190                 }
191             }
192             if (j == numChildren) {
193                 // Child not found, create it
194                 child = new UriMatcher();
195                 if (token.equals("#")) {
196                     child.mWhich = NUMBER;
197                 } else if (token.equals("*")) {
198                     child.mWhich = TEXT;
199                 } else {
200                     child.mWhich = EXACT;
201                 }
202                 child.mText = token;
203                 node.mChildren.add(child);
204                 node = child;
205             }
206         }
207         node.mCode = code;
208     }
209 
210     static final Pattern PATH_SPLIT_PATTERN = Pattern.compile("/");
211 
212     /**
213      * Try to match against the path in a url.
214      *
215      * @param uri       The url whose path we will match against.
216      *
217      * @return  The code for the matched node (added using addURI),
218      * or -1 if there is no matched node.
219      */
220     public int match(Uri uri)
221     {
222         final List<String> pathSegments = uri.getPathSegments();
223         final int li = pathSegments.size();
224 
225         UriMatcher node = this;
226 
227         if (li == 0 && uri.getAuthority() == null) {
228             return this.mCode;
229         }
230 
231         for (int i=-1; i<li; i++) {
232             String u = i < 0 ? uri.getAuthority() : pathSegments.get(i);
233             ArrayList<UriMatcher> list = node.mChildren;
234             if (list == null) {
235                 break;
236             }
237             node = null;
238             int lj = list.size();
239             for (int j=0; j<lj; j++) {
240                 UriMatcher n = list.get(j);
241           which_switch:
242                 switch (n.mWhich) {
243                     case EXACT:
244                         if (n.mText.equals(u)) {
245                             node = n;
246                         }
247                         break;
248                     case NUMBER:
249                         int lk = u.length();
250                         for (int k=0; k<lk; k++) {
251                             char c = u.charAt(k);
252                             if (c < '0' || c > '9') {
253                                 break which_switch;
254                             }
255                         }
256                         node = n;
257                         break;
258                     case TEXT:
259                         node = n;
260                         break;
261                 }
262                 if (node != null) {
263                     break;
264                 }
265             }
266             if (node == null) {
267                 return NO_MATCH;
268             }
269         }
270 
271         return node.mCode;
272     }
273 
274     private static final int EXACT = 0;
275     private static final int NUMBER = 1;
276     private static final int TEXT = 2;
277 
278     private int mCode;
279     private int mWhich;
280     private String mText;
281     private ArrayList<UriMatcher> mChildren;
282 }
283