1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 /* 22 * Copyright (c) 1999 by Sun Microsystems, Inc. 23 * All rights reserved. 24 * 25 */ 26 27 // ServiceStore.java: Interface for different storage implementations 28 // Author: James Kempf 29 // Created On: Thu Oct 16 07:46:45 1997 30 // Last Modified By: James Kempf 31 // Last Modified On: Wed Feb 17 09:28:53 1999 32 // Update Count: 91 33 // 34 35 package com.sun.slp; 36 37 import java.util.*; 38 import java.io.*; 39 40 /** 41 * ServiceStore specifies the interface between the storage back end for 42 * the SLP DA/slpd and the communications front end. There can be 43 * various implementations of the ServiceStore. The ServiceStoreFactory 44 * class is responsible for instantiating the ServiceStore object. 45 * Each ServiceStore implementation must also supply ServiceRecord 46 * objects. 47 * 48 * @author James Kempf 49 */ 50 51 interface ServiceStore { 52 53 /** 54 * Key for fetching attribute values from findAttributes() returned 55 * hashtable. 56 */ 57 58 final static String FA_ATTRIBUTES = "FA_ATTRIBUTES"; 59 60 /** 61 * Key for fetching attribute auth block from findAttributes() returned 62 * hashtable. 63 */ 64 65 final static String FA_SIG = "FA_SIG"; 66 67 /** 68 * Key for fetching hashtable of service URLs v.s. scopes values from 69 * findServices() returned hashtable. 70 */ 71 72 final static String FS_SERVICES = "FS_SERVICES"; 73 74 /** 75 * Key for fetching hashtable of service URLs v.s. signatures from 76 * findServices() returned hashtable. 77 */ 78 79 final static String FS_SIGTABLE = "FS_SIGTABLE"; 80 81 /** 82 * The ServiceRecord interface specifies the record structure of 83 * stored in the ServiceStore. The methods are all property 84 * accessors. 85 * 86 * @author James Kempf 87 */ 88 89 interface ServiceRecord { 90 91 /** 92 * Return the ServiceURL for the record. 93 * 94 * @return The record's service URL. 95 */ 96 97 ServiceURL getServiceURL(); 98 99 /** 100 * Return the Vector of ServiceLocationAttribute objects for the record 101 * 102 * @return Vector of ServiceLocationAttribute objects for the record. 103 */ 104 105 Vector getAttrList(); 106 107 /** 108 * Return the locale in which this record is registered. 109 * 110 * @return The language locale in which this record is registered. 111 */ 112 113 Locale getLocale(); 114 115 /** 116 * Return the Vector of scopes in which this record is registered. 117 * 118 * @return The Vector of scopes in which this record is registered. 119 */ 120 121 Vector getScopes(); 122 123 /** 124 * Return the expiration time for the record. This informs the 125 * service store when the record should expire and be removed 126 * from the table. 127 * 128 * @return The expiration time for the record. 129 */ 130 131 long getExpirationTime(); 132 133 /** 134 * Return the URL signature, or null if there's none. 135 * 136 * @return auth block Hashtable for URL signature. 137 */ 138 139 Hashtable getURLSignature(); 140 141 /** 142 * Return the attribute signature, or null if there's none. 143 * 144 * @return auth block Hashtable for attribute signature. 145 */ 146 147 Hashtable getAttrSignature(); 148 149 } 150 151 // 152 // ServiceStore interface methods. 153 // 154 155 /** 156 * On first call, return the time since the last stateless reboot 157 * of the ServiceStore for a stateful store. Otherwise, return the 158 * current time. This is for DAs. 159 * 160 * @return A Long giving the time since the last stateless reboot, 161 * in NTP format. 162 */ 163 164 long getStateTimestamp(); 165 166 /** 167 * Age out all records whose time has expired. 168 * 169 * @param deleted A Vector for return of ServiceStore.Service records 170 * containing deleted services. 171 * @return The time interval until another table walk must be done, 172 * in milliseconds. 173 * 174 */ 175 176 long ageOut(Vector deleted); 177 178 /** 179 * Create a new registration with the given parameters. 180 * 181 * @param url The ServiceURL. 182 * @param attrs The Vector of ServiceLocationAttribute objects. 183 * @param locale The Locale. 184 * @param scopes Vector of scopes in which this record is registered. 185 * @param urlSig Hashtable for URL signatures, or null if none. 186 * @param attrSig Hashtable for URL signatures, or null if none. 187 * @return True if there is an already existing registration which 188 * this one replaced. 189 * @exception ServiceLocationException Thrown if any 190 * error occurs during registration or if the table 191 * requires a network connection that failed. This 192 * includes timeout failures. 193 */ 194 195 boolean register(ServiceURL url, Vector attrs, 196 Vector scopes, Locale locale, 197 Hashtable urlSig, Hashtable attrSig) 198 throws ServiceLocationException; 199 200 /** 201 * Deregister a ServiceURL from the database for every locale 202 * and every scope. There will be only one record for each URL 203 * and locale deregistered, regardless of the number of scopes in 204 * which the URL was registered, since the attributes will be the 205 * same in each scope if the locale is the same. 206 * 207 * @param url The ServiceURL 208 * @param scopes Vector of scopes. 209 * @param urlSig The URL signature, if any. 210 * @exception ServiceLocationException Thrown if the 211 * ServiceStore does not contain the URL, or if any 212 * error occurs during the operation, or if the table 213 * requires a network connection that failed. This 214 * includes timeout failures. 215 */ 216 217 void deregister(ServiceURL url, Vector scopes, Hashtable urlSig) 218 throws ServiceLocationException; 219 220 /** 221 * Update the service registration with the new parameters, adding 222 * attributes and updating the service URL's lifetime. 223 * 224 * @param url The ServiceURL. 225 * @param attrs The Vector of ServiceLocationAttribute objects. 226 * @param locale The Locale. 227 * @param scopes Vector of scopes in which this record is registered. 228 * @exception ServiceLocationException Thrown if any 229 * error occurs during registration or if the table 230 * requires a network connection that failed. This 231 * includes timeout failures. 232 */ 233 234 void updateRegistration(ServiceURL url, Vector attrs, 235 Vector scopes, Locale locale) 236 throws ServiceLocationException; 237 238 /** 239 * Delete the attributes from the ServiceURL object's table entries. 240 * Delete for every locale that has the attributes and every scope. 241 * Note that the attribute tags must be lower-cased in the locale of 242 * the registration, not in the locale of the request. 243 * 244 * @param url The ServiceURL. 245 * @param scopes Vector of scopes. 246 * @param attrTags The Vector of String 247 * objects specifying the attribute tags of 248 * the attributes to delete. 249 * @param locale Locale of the request. 250 * @exception ServiceLocationException Thrown if the 251 * ServiceStore does not contain the URL or if any 252 * error occurs during the operation or if the table 253 * requires a network connection that failed. This 254 * includes timeout failures. 255 */ 256 257 void 258 deleteAttributes(ServiceURL url, 259 Vector scopes, 260 Vector attrTags, 261 Locale locale) 262 throws ServiceLocationException; 263 264 /** 265 * Return a Vector of String containing the service types for this 266 * scope and naming authority. If there are none, an empty vector is 267 * returned. 268 * 269 * @param namingAuthority The namingAuthority, or "*" if for all. 270 * @param scopes The scope names. 271 * @return A Vector of String objects that are the type names, or 272 * an empty vector if there are none. 273 * @exception ServiceLocationException Thrown if any 274 * error occurs during the operation or if the table 275 * requires a network connection that failed. This 276 * includes timeout failures. 277 */ 278 279 Vector findServiceTypes(String namingAuthority, Vector scopes) 280 throws ServiceLocationException; 281 282 /** 283 * Return a Hashtable with the key FS_SERVICES matched to the 284 * hashtable of ServiceURL objects as key and a vector 285 * of their scopes as value, and the key FS_SIGTABLE 286 * matched to a hashtable with ServiceURL objects as key 287 * and the auth block Hashtable for the URL (if any) for value. The 288 * returned service URLs will match the service type, scope, query, 289 * and locale. If there are no signatures, the FS_SIGTABLE 290 * key returns null. If there are no 291 * registrations in any locale, FS_SERVICES is bound to an 292 * empty table. 293 * 294 * @param serviceType The service type name. 295 * @param scope The scope name. 296 * @param query The query, with any escaped characters as yet unprocessed. 297 * @param locale The locale in which to lowercase query and search. 298 * @return A Hashtable with the key FS_SERVICES matched to the 299 * hashtable of ServiceURL objects as key and a vector 300 * of their scopes as value, and the key FS_SIGTABLE 301 * matched to a hashtable with ServiceURL objects as key 302 * and the auth block Hashtable for the URL (if any) for value. 303 * If there are no registrations in any locale, FS_SERVICES 304 * is bound to an empty table. 305 * @exception ServiceLocationException Thrown if a parse error occurs 306 * during query parsing or if any 307 * error occurs during the operation or if the table 308 * requires a network connection that failed. This 309 * includes timeout failures. 310 */ 311 312 Hashtable findServices(String serviceType, 313 Vector scopes, 314 String query, 315 Locale locale) 316 throws ServiceLocationException; 317 318 /** 319 * Return a Hashtable with key FA_ATTRIBUTES matched to the 320 * vector of ServiceLocationAttribute objects and key FA_SIG 321 * matched to the auth block Hashtable for the attributes (if any) 322 * The attribute objects will have tags matching the tags in 323 * the input parameter vector. If there are no registrations in any locale, 324 * FA_ATTRIBUTES is an empty vector. 325 * 326 * @param url The ServiceURL for which the records should be returned. 327 * @param scopes The scope names for which to search. 328 * @param attrTags The Vector of String 329 * objects containing the attribute tags. 330 * @param locale The locale in which to lower case tags and search. 331 * @return A Hashtable with a vector of ServiceLocationAttribute objects 332 * as the key and the auth block Hashtable for the attributes 333 * (if any) as the value. 334 * If there are no registrations in any locale, FA_ATTRIBUTES 335 * is an empty vector. 336 * @exception ServiceLocationException Thrown if any 337 * error occurs during the operation or if the table 338 * requires a network connection that failed. This 339 * includes timeout failures. An error should be 340 * thrown if the tag vector is for a partial request 341 * and any of the scopes are protected. 342 */ 343 344 Hashtable findAttributes(ServiceURL url, 345 Vector scopes, 346 Vector attrTags, 347 Locale locale) 348 throws ServiceLocationException; 349 350 /** 351 * Return a Vector of ServiceLocationAttribute objects with attribute tags 352 * matching the tags in the input parameter vector for all service URL's 353 * of the service type. If there are no registrations 354 * in any locale, an empty vector is returned. 355 * 356 * @param serviceType The service type name. 357 * @param scopes The scope names for which to search. 358 * @param attrTags The Vector of String 359 * objects containing the attribute tags. 360 * @param locale The locale in which to lower case tags. 361 * @return A Vector of ServiceLocationAttribute objects matching the query. 362 * If no match occurs but there are registrations 363 * in other locales, null is returned. If there are no registrations 364 * in any locale, an empty vector is returned. 365 * @exception ServiceLocationException Thrown if any 366 * error occurs during the operation or if the table 367 * requires a network connection that failed. This 368 * includes timeout failures. An error should also be 369 * signalled if any of the scopes are protected. 370 */ 371 372 Vector findAttributes(String serviceType, 373 Vector scopes, 374 Vector attrTags, 375 Locale locale) 376 throws ServiceLocationException; 377 378 /** 379 * Dump the service store to the log. 380 * 381 */ 382 383 void dumpServiceStore(); 384 385 /** 386 * Obtain the record matching the service URL and locale. 387 * 388 * @param URL The service record to match. 389 * @param locale The locale of the record. 390 * @return The ServiceRecord object, or null if none. 391 */ 392 393 public ServiceRecord 394 getServiceRecord(ServiceURL URL, Locale locale); 395 396 /** 397 * Obtains service records with scopes matching from vector scopes. 398 * If scopes is null, then returns all records. 399 * 400 * @param scopes Vector of scopes to match. 401 * @return Enumeration Of ServiceRecord Objects. 402 */ 403 404 Enumeration getServiceRecordsByScope(Vector scopes); 405 406 } 407