/* * CDDL HEADER START * * The contents of this file are subject to the terms of the * Common Development and Distribution License (the "License"). * You may not use this file except in compliance with the License. * * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE * or http://www.opensolaris.org/os/licensing. * See the License for the specific language governing permissions * and limitations under the License. * * When distributing Covered Code, include this CDDL HEADER in each * file and include the License file at usr/src/OPENSOLARIS.LICENSE. * If applicable, add the following below this CDDL HEADER, with the * fields enclosed by brackets "[]" replaced with your own identifying * information: Portions Copyright [yyyy] [name of copyright owner] * * CDDL HEADER END */ /* * Copyright (c) 1999 by Sun Microsystems, Inc. * All rights reserved. * */ // ServiceStore.java: Interface for different storage implementations // Author: James Kempf // Created On: Thu Oct 16 07:46:45 1997 // Last Modified By: James Kempf // Last Modified On: Wed Feb 17 09:28:53 1999 // Update Count: 91 // package com.sun.slp; import java.util.*; import java.io.*; /** * ServiceStore specifies the interface between the storage back end for * the SLP DA/slpd and the communications front end. There can be * various implementations of the ServiceStore. The ServiceStoreFactory * class is responsible for instantiating the ServiceStore object. * Each ServiceStore implementation must also supply ServiceRecord * objects. * * @author James Kempf */ interface ServiceStore { /** * Key for fetching attribute values from findAttributes() returned * hashtable. */ final static String FA_ATTRIBUTES = "FA_ATTRIBUTES"; /** * Key for fetching attribute auth block from findAttributes() returned * hashtable. */ final static String FA_SIG = "FA_SIG"; /** * Key for fetching hashtable of service URLs v.s. scopes values from * findServices() returned hashtable. */ final static String FS_SERVICES = "FS_SERVICES"; /** * Key for fetching hashtable of service URLs v.s. signatures from * findServices() returned hashtable. */ final static String FS_SIGTABLE = "FS_SIGTABLE"; /** * The ServiceRecord interface specifies the record structure of * stored in the ServiceStore. The methods are all property * accessors. * * @author James Kempf */ interface ServiceRecord { /** * Return the ServiceURL for the record. * * @return The record's service URL. */ ServiceURL getServiceURL(); /** * Return the Vector of ServiceLocationAttribute objects for the record * * @return Vector of ServiceLocationAttribute objects for the record. */ Vector getAttrList(); /** * Return the locale in which this record is registered. * * @return The language locale in which this record is registered. */ Locale getLocale(); /** * Return the Vector of scopes in which this record is registered. * * @return The Vector of scopes in which this record is registered. */ Vector getScopes(); /** * Return the expiration time for the record. This informs the * service store when the record should expire and be removed * from the table. * * @return The expiration time for the record. */ long getExpirationTime(); /** * Return the URL signature, or null if there's none. * * @return auth block Hashtable for URL signature. */ Hashtable getURLSignature(); /** * Return the attribute signature, or null if there's none. * * @return auth block Hashtable for attribute signature. */ Hashtable getAttrSignature(); } // // ServiceStore interface methods. // /** * On first call, return the time since the last stateless reboot * of the ServiceStore for a stateful store. Otherwise, return the * current time. This is for DAs. * * @return A Long giving the time since the last stateless reboot, * in NTP format. */ long getStateTimestamp(); /** * Age out all records whose time has expired. * * @param deleted A Vector for return of ServiceStore.Service records * containing deleted services. * @return The time interval until another table walk must be done, * in milliseconds. * */ long ageOut(Vector deleted); /** * Create a new registration with the given parameters. * * @param url The ServiceURL. * @param attrs The Vector of ServiceLocationAttribute objects. * @param locale The Locale. * @param scopes Vector of scopes in which this record is registered. * @param urlSig Hashtable for URL signatures, or null if none. * @param attrSig Hashtable for URL signatures, or null if none. * @return True if there is an already existing registration which * this one replaced. * @exception ServiceLocationException Thrown if any * error occurs during registration or if the table * requires a network connection that failed. This * includes timeout failures. */ boolean register(ServiceURL url, Vector attrs, Vector scopes, Locale locale, Hashtable urlSig, Hashtable attrSig) throws ServiceLocationException; /** * Deregister a ServiceURL from the database for every locale * and every scope. There will be only one record for each URL * and locale deregistered, regardless of the number of scopes in * which the URL was registered, since the attributes will be the * same in each scope if the locale is the same. * * @param url The ServiceURL * @param scopes Vector of scopes. * @param urlSig The URL signature, if any. * @exception ServiceLocationException Thrown if the * ServiceStore does not contain the URL, or if any * error occurs during the operation, or if the table * requires a network connection that failed. This * includes timeout failures. */ void deregister(ServiceURL url, Vector scopes, Hashtable urlSig) throws ServiceLocationException; /** * Update the service registration with the new parameters, adding * attributes and updating the service URL's lifetime. * * @param url The ServiceURL. * @param attrs The Vector of ServiceLocationAttribute objects. * @param locale The Locale. * @param scopes Vector of scopes in which this record is registered. * @exception ServiceLocationException Thrown if any * error occurs during registration or if the table * requires a network connection that failed. This * includes timeout failures. */ void updateRegistration(ServiceURL url, Vector attrs, Vector scopes, Locale locale) throws ServiceLocationException; /** * Delete the attributes from the ServiceURL object's table entries. * Delete for every locale that has the attributes and every scope. * Note that the attribute tags must be lower-cased in the locale of * the registration, not in the locale of the request. * * @param url The ServiceURL. * @param scopes Vector of scopes. * @param attrTags The Vector of String * objects specifying the attribute tags of * the attributes to delete. * @param locale Locale of the request. * @exception ServiceLocationException Thrown if the * ServiceStore does not contain the URL or if any * error occurs during the operation or if the table * requires a network connection that failed. This * includes timeout failures. */ void deleteAttributes(ServiceURL url, Vector scopes, Vector attrTags, Locale locale) throws ServiceLocationException; /** * Return a Vector of String containing the service types for this * scope and naming authority. If there are none, an empty vector is * returned. * * @param namingAuthority The namingAuthority, or "*" if for all. * @param scopes The scope names. * @return A Vector of String objects that are the type names, or * an empty vector if there are none. * @exception ServiceLocationException Thrown if any * error occurs during the operation or if the table * requires a network connection that failed. This * includes timeout failures. */ Vector findServiceTypes(String namingAuthority, Vector scopes) throws ServiceLocationException; /** * Return a Hashtable with the key FS_SERVICES matched to the * hashtable of ServiceURL objects as key and a vector * of their scopes as value, and the key FS_SIGTABLE * matched to a hashtable with ServiceURL objects as key * and the auth block Hashtable for the URL (if any) for value. The * returned service URLs will match the service type, scope, query, * and locale. If there are no signatures, the FS_SIGTABLE * key returns null. If there are no * registrations in any locale, FS_SERVICES is bound to an * empty table. * * @param serviceType The service type name. * @param scope The scope name. * @param query The query, with any escaped characters as yet unprocessed. * @param locale The locale in which to lowercase query and search. * @return A Hashtable with the key FS_SERVICES matched to the * hashtable of ServiceURL objects as key and a vector * of their scopes as value, and the key FS_SIGTABLE * matched to a hashtable with ServiceURL objects as key * and the auth block Hashtable for the URL (if any) for value. * If there are no registrations in any locale, FS_SERVICES * is bound to an empty table. * @exception ServiceLocationException Thrown if a parse error occurs * during query parsing or if any * error occurs during the operation or if the table * requires a network connection that failed. This * includes timeout failures. */ Hashtable findServices(String serviceType, Vector scopes, String query, Locale locale) throws ServiceLocationException; /** * Return a Hashtable with key FA_ATTRIBUTES matched to the * vector of ServiceLocationAttribute objects and key FA_SIG * matched to the auth block Hashtable for the attributes (if any) * The attribute objects will have tags matching the tags in * the input parameter vector. If there are no registrations in any locale, * FA_ATTRIBUTES is an empty vector. * * @param url The ServiceURL for which the records should be returned. * @param scopes The scope names for which to search. * @param attrTags The Vector of String * objects containing the attribute tags. * @param locale The locale in which to lower case tags and search. * @return A Hashtable with a vector of ServiceLocationAttribute objects * as the key and the auth block Hashtable for the attributes * (if any) as the value. * If there are no registrations in any locale, FA_ATTRIBUTES * is an empty vector. * @exception ServiceLocationException Thrown if any * error occurs during the operation or if the table * requires a network connection that failed. This * includes timeout failures. An error should be * thrown if the tag vector is for a partial request * and any of the scopes are protected. */ Hashtable findAttributes(ServiceURL url, Vector scopes, Vector attrTags, Locale locale) throws ServiceLocationException; /** * Return a Vector of ServiceLocationAttribute objects with attribute tags * matching the tags in the input parameter vector for all service URL's * of the service type. If there are no registrations * in any locale, an empty vector is returned. * * @param serviceType The service type name. * @param scopes The scope names for which to search. * @param attrTags The Vector of String * objects containing the attribute tags. * @param locale The locale in which to lower case tags. * @return A Vector of ServiceLocationAttribute objects matching the query. * If no match occurs but there are registrations * in other locales, null is returned. If there are no registrations * in any locale, an empty vector is returned. * @exception ServiceLocationException Thrown if any * error occurs during the operation or if the table * requires a network connection that failed. This * includes timeout failures. An error should also be * signalled if any of the scopes are protected. */ Vector findAttributes(String serviceType, Vector scopes, Vector attrTags, Locale locale) throws ServiceLocationException; /** * Dump the service store to the log. * */ void dumpServiceStore(); /** * Obtain the record matching the service URL and locale. * * @param URL The service record to match. * @param locale The locale of the record. * @return The ServiceRecord object, or null if none. */ public ServiceRecord getServiceRecord(ServiceURL URL, Locale locale); /** * Obtains service records with scopes matching from vector scopes. * If scopes is null, then returns all records. * * @param scopes Vector of scopes to match. * @return Enumeration Of ServiceRecord Objects. */ Enumeration getServiceRecordsByScope(Vector scopes); }