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 getServiceURL()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 getAttrList()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 getLocale()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 getScopes()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 getExpirationTime()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 getURLSignature()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 getAttrSignature()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 getStateTimestamp()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 ageOut(Vector deleted)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 register(ServiceURL url, Vector attrs, Vector scopes, Locale locale, Hashtable urlSig, Hashtable attrSig)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 deregister(ServiceURL url, Vector scopes, Hashtable urlSig)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 updateRegistration(ServiceURL url, Vector attrs, Vector scopes, Locale locale)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 deleteAttributes(ServiceURL url, Vector scopes, Vector attrTags, Locale locale)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 findServiceTypes(String namingAuthority, Vector scopes)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 findServices(String serviceType, Vector scopes, String query, Locale locale)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 findAttributes(ServiceURL url, Vector scopes, Vector attrTags, Locale locale)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 findAttributes(String serviceType, Vector scopes, Vector attrTags, Locale locale)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 dumpServiceStore()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 getServiceRecord(ServiceURL URL, Locale locale)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 getServiceRecordsByScope(Vector scopes)404 Enumeration getServiceRecordsByScope(Vector scopes); 405 406 } 407