xref: /illumos-gate/usr/src/lib/libslp/javalib/com/sun/slp/ServiceStore.java (revision 9a70fc3be3b1e966bf78825cdb8d509963a6f0a1)
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