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