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