xref: /titanic_41/usr/src/lib/libslp/javalib/com/sun/slp/Locator.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 //  UserAgent.java:   Interface for the SLP User Agent operations
28 //  Author:           James Kempf
29 //  Created On:       Mon Jul  7 09:15:56 1997
30 //  Last Modified By: James Kempf
31 //  Last Modified On: Wed May 13 17:46:29 1998
32 //  Update Count:     17
33 //
34 
35 package com.sun.slp;
36 
37 import java.util.*;
38 
39 /**
40  * The Locator interface allows clients to query SLP for existing
41  * services, scopes, and service instances, and to query about attributes
42  * of a particular service instance.
43  *
44  * @see ServiceLocationManager
45  *
46  * @author James Kempf, Erik Guttman
47  */
48 
49 public interface Locator {
50 
51     /**
52      * Return the Locator's locale object.
53      *
54      * @return The Locale object.
55      */
56 
getLocale()57     Locale getLocale();
58 
59     /**
60      * Return an enumeration of known service types for this scope and naming
61      * authority.  Unless a proprietary or experimental service is being
62      * discovered, the namingAuthority parameter should be the empty
63      * string, "".
64      *
65      * @param namingAuthority	The naming authority, "" for default,
66      *                           '*' for any naming authority.
67      * @param scopes	The SLP scopes of the types.
68      * @return ServiceLocationEnumeration of ServiceType objects for
69      *	      the service type names.
70      * @exception IllegalArgumentException If any of the parameters are
71      *					  null or syntactically incorrect.
72      * @exception ServiceLocationException An exception is thrown if the
73      *					  operation fails.
74      */
75 
findServiceTypes(String namingAuthority, Vector scopes)76     public ServiceLocationEnumeration findServiceTypes(String namingAuthority,
77 						       Vector scopes)
78 	throws ServiceLocationException;
79 
80     /**
81      * Return an enumeration of ServiceURL objects for services matching
82      * the query. The services are returned from the locale of the
83      * locator.
84      *
85      * @param type	The type of the service (e.g. printer, etc.).
86      * @param scopes	The SLP scopes of the service types.
87      * @param query		A string with the SLP query.
88      * @return ServiceLocationEnumeration of ServiceURL objects for
89      *	      services matching the
90      *         attributes.
91      * @exception ServiceLocationException An exception is returned if the
92      *					  operation fails.
93      * @see ServiceURL
94      */
95 
findServices(ServiceType type, Vector scopes, String query)96     public ServiceLocationEnumeration findServices(ServiceType type,
97 						   Vector scopes,
98 						   String query)
99 	throws ServiceLocationException;
100 
101     /**
102      * Return the attributes for the service URL, using the locale
103      * of the locator.
104      *
105      * @param URL	The service URL.
106      * @param scopes	The SLP scopes of the service.
107      * @param attributeIds A vector of strings identifying the desired
108      *			  attributes. A null value means return all
109      *			  the attributes.  <b>Partial id strings</b> may
110      *                     begin with '*' to match all ids which end with
111      *                     the given suffix, or end with '*' to match all
112      *                     ids which begin with a given prefix, or begin
113      *                     and end with '*' to do substring matching for
114      *                     ids containing the given partial id.
115      * @return ServiceLocationEnumeration of ServiceLocationAttribute
116      *         objects matching the ids.
117      * @exception ServiceLocationException An exception is returned if the
118      *					  operation fails.
119      * @exception IllegalArgumentException If any of the parameters are
120      *					  null or syntactically incorrect.
121      * @see ServiceLocationAttribute
122      *
123      */
124 
findAttributes(ServiceURL URL, Vector scopes, Vector attributeIds)125     public ServiceLocationEnumeration findAttributes(ServiceURL URL,
126 						     Vector scopes,
127 						     Vector attributeIds)
128 	throws ServiceLocationException;
129 
130     /**
131      * Return all attributes for all service URL's having this
132      * service type in the locale of the Locator.
133      *
134      * @param type The service type.
135      * @param scopes	The SLP scopes of the service type.
136      * @param attributeIds A vector of strings identifying the desired
137      *			  attributes. A null value means return all
138      *			  the attributes.  <b>Partial id strings</b> may
139      *                     begin with '*' to match all ids which end with
140      *                     the given suffix, or end with '*' to match all
141      *                     ids which begin with a given prefix, or begin
142      *                     and end with '*' to do substring matching for
143      *                     ids containing the given partial id.
144      * @return ServiceLocationEnumeration of ServiceLocationAttribute
145      *         objects matching the ids.
146      * @exception ServiceLocationException An exception is returned if the
147      *					  operation fails.
148      * @exception IllegalArgumentException If any of the parameters are
149      *					  null or syntactically incorrect.
150      * @see ServiceLocationAttribute
151      *
152      */
153 
findAttributes(ServiceType type, Vector scopes, Vector attributeIds)154     public ServiceLocationEnumeration findAttributes(ServiceType type,
155 						     Vector scopes,
156 						     Vector attributeIds)
157 	throws ServiceLocationException;
158 
159 
160 }
161