View Javadoc

1   /*
2    * 
3    * Copyright 2005 Sun Microsystems, Inc.
4    * 
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    * 
9    *  http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   * 
17   * Note: Changes by the Jgroup team are marked ** GREG **.
18   * 
19   */
20  package com.sun.jini.reggie;
21  
22  import java.rmi.MarshalledObject;
23  import java.rmi.Remote;
24  import java.rmi.RemoteException;
25  
26  import net.jini.admin.Administrable;
27  import net.jini.admin.JoinAdmin;
28  import net.jini.core.discovery.LookupLocator;
29  import net.jini.core.event.EventRegistration;
30  import net.jini.core.event.RemoteEventListener;
31  import net.jini.core.lease.UnknownLeaseException;
32  import net.jini.core.lookup.ServiceID;
33  import net.jini.core.lookup.ServiceRegistration;
34  import net.jini.id.Uuid;
35  import net.jini.lookup.DiscoveryAdmin;
36  
37  import com.sun.jini.admin.DestroyAdmin;
38  import com.sun.jini.proxy.MarshalledWrapper;
39  import com.sun.jini.start.ServiceProxyAccessor;
40  
41  /**
42   * Registrar defines the private protocol between the various client-side
43   * proxies and the registrar server.
44   * <p>
45   * The declared methods are pretty straightforward transformations of the
46   * ServiceRegistrar and ServiceRegistration interfaces, with external classes
47   * (ServiceItem, ServiceTemplate, ServiceMatches, Entry) converted to internal
48   * classes (Item, Template, Matches, EntryRep).  In addition, there are
49   * methods for transformed Lease and LeaseMap interfaces, for service and
50   * event leases.
51   *
52   * @author Sun Microsystems, Inc.
53   *
54   */
55  interface Registrar extends Remote, ServiceProxyAccessor, Administrable, DiscoveryAdmin,
56      JoinAdmin, DestroyAdmin
57  {
58    /**
59     * Register a new service or re-register an existing service.
60     * @see net.jini.core.lookup.ServiceRegistrar#register
61     */
62    ServiceRegistration register(Item item, long leaseDuration) throws RemoteException;
63  
64    /**
65     * Returns the service object (i.e., just ServiceItem.service) from an
66     * item matching the template, or null if there is no match.
67     * @see net.jini.core.lookup.ServiceRegistrar#lookup
68     * 
69     * ** GREG ** Changed to return an array with service objects.
70     */
71    MarshalledWrapper[] lookup(Template tmpl) throws RemoteException;
72  
73    /**
74     * Returns at most maxMatches items matching the template, plus the total
75     * number of items that match the template.
76     * @see net.jini.core.lookup.ServiceRegistrar#lookup
77     */
78    Matches lookup(Template tmpl, int maxMatches) throws RemoteException;
79  
80    /**
81     * Registers for event notification.
82     * @see net.jini.core.lookup.ServiceRegistrar#notify
83     */
84    EventRegistration notify(Template tmpl, int transitions, RemoteEventListener listener,
85        MarshalledObject handback, long leaseDuration) throws RemoteException;
86  
87    /**
88     * Looks at all service items that match the specified template, finds
89     * every entry (among those service items) that either doesn't match any
90     * entry templates or is a subclass of at least one matching entry
91     * template, and returns the set of the (most specific) classes of those
92     * entries.
93     * @see net.jini.core.lookup.ServiceRegistrar#getEntryClasses
94     */
95    EntryClassBase[] getEntryClasses(Template tmpl) throws RemoteException;
96  
97    /**
98     * Looks at all service items that match the specified template, finds
99     * every entry (among those service items) that matches
100    * tmpl.attributeSetTemplates[setIndex], and returns the set of values
101    * of the specified field of those entries.
102    * The field name has been converted to an index (fields numbered
103    * from super to subclass).
104    *
105    * @see net.jini.core.lookup.ServiceRegistrar#getFieldValues
106    */
107   Object[] getFieldValues(Template tmpl, int setIndex, int field) throws RemoteException;
108 
109   /**
110    * Looks at all service items that match the specified template, and for
111    * every service item finds the most specific type (class or interface)
112    * or types the service item is an instance of that are neither equal to,
113    * nor a superclass of, any of the service types in the template and that
114    * have names that start with the specified prefix, and returns the set
115    * of all such types.
116    * @see net.jini.core.lookup.ServiceRegistrar#getServiceTypes
117    */
118   ServiceTypeBase[] getServiceTypes(Template tmpl, String prefix) throws RemoteException;
119 
120   /**
121    * Returns a LookupLocator that can be used if necessary for unicast
122    * discovery of the lookup service.
123    * @see net.jini.core.lookup.ServiceRegistrar#getLocator
124    */
125   LookupLocator getLocator() throws RemoteException;
126 
127   /**
128    * Adds the specified attribute sets (those that aren't duplicates of
129    * existing attribute sets) to the registered service item.
130    * @see net.jini.core.lookup.ServiceRegistration#addAttributes
131    */
132   void addAttributes(ServiceID serviceID, Uuid leaseID, EntryRep[] attrSets)
133       throws UnknownLeaseException, RemoteException;
134 
135   /**
136    * Modifies existing attribute sets of a registered service item.
137    * @see net.jini.core.lookup.ServiceRegistration#modifyAttributes
138    */
139   void modifyAttributes(ServiceID serviceID, Uuid leaseID, EntryRep[] attrSetTmpls,
140       EntryRep[] attrSets) throws UnknownLeaseException, RemoteException;
141 
142   /**
143    * Deletes all of the service item's existing attributes, and replaces
144    * them with the specified attribute sets.
145    * @see net.jini.core.lookup.ServiceRegistration#setAttributes
146    */
147   void setAttributes(ServiceID serviceID, Uuid leaseID, EntryRep[] attrSets)
148       throws UnknownLeaseException, RemoteException;
149 
150   /**
151    * Cancels a service lease.
152    * @see net.jini.core.lease.Lease#cancel
153    */
154   void cancelServiceLease(ServiceID serviceID, Uuid leaseID) throws UnknownLeaseException,
155       RemoteException;
156 
157   /**
158    * Renews a service lease.
159    * @see net.jini.core.lease.Lease#renew
160    */
161   long renewServiceLease(ServiceID serviceID, Uuid leaseID, long duration)
162       throws UnknownLeaseException, RemoteException;
163 
164   /**
165    * Cancels an event lease.
166    * @see net.jini.core.lease.Lease#cancel
167    */
168   void cancelEventLease(long eventID, Uuid leaseID) throws UnknownLeaseException,
169       RemoteException;
170 
171   /**
172    * Renews an event lease.
173    * @see net.jini.core.lease.Lease#renew
174    */
175   long renewEventLease(long eventID, Uuid leaseID, long duration)
176       throws UnknownLeaseException, RemoteException;
177 
178   /**
179    * Renews service and event leases from a LeaseMap.
180    * @see net.jini.core.lease.LeaseMap#renewAll
181    */
182   RenewResults renewLeases(Object[] regIDs, Uuid[] leaseIDs, long[] durations)
183       throws RemoteException;
184 
185   /**
186    * Cancels service and event leases from a LeaseMap.
187    * @see net.jini.core.lease.LeaseMap#cancelAll
188    */
189   Exception[] cancelLeases(Object[] regIDs, Uuid[] leaseIDs) throws RemoteException;
190 }