Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 1e1c7c6f7237d246f778962546abb5a82ab09785 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
/*******************************************************************************
 * Copyright (c) 2004 Composent, Inc. and others. All rights reserved. This
 * program and the accompanying materials are made available under the terms of
 * the Eclipse Public License v1.0 which accompanies this distribution, and is
 * available at http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors: Composent, Inc. - initial API and implementation
 ******************************************************************************/

package org.eclipse.ecf.discovery;

import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.ecf.core.identity.Namespace;
import org.eclipse.ecf.core.util.ECFException;
import org.eclipse.ecf.discovery.identity.*;

/**
 * Entry point discovery container adapter. This interface exposes the ability
 * to add/remove listeners for newly discovered services and service types,
 * register and unregister locally provided services, and get (synch) and
 * request (asynchronous) service info from a remote service provider.
 * <p>
 * This interface can be used by container provider implementations as an
 * adapter so that calls to
 * IContainer.getAdapter(IDiscoveryContainerAdapter.class) will return a
 * non-null instance of a class that implements this interface. Clients can then
 * proceed to use this interface to interact with the given discovery
 * implementation.
 * 
 */
public interface IDiscoveryContainerAdapter extends IAdaptable {

	/** ECF Service Property Names **/
	public static final String CONTAINER_FACTORY_NAME_PROPERTY = "org.eclipse.ecf.containerFactoryName"; //$NON-NLS-1$
	public static final String CONTAINER_CONNECT_TARGET = "org.eclipse.ecf.connectTarget"; //$NON-NLS-1$
	public static final String CONTAINER_CONNECT_TARGET_PROTOCOL = "org.eclipse.ecf.connectTargetProtocol"; //$NON-NLS-1$
	public static final String CONTAINER_CONNECT_TARGET_PATH = "org.eclipse.ecf.connectTargetPath"; //$NON-NLS-1$
	public static final String CONTAINER_CONNECT_REQUIRES_PASSWORD = "org.eclipse.ecf.connectContextRequiresPassword"; //$NON-NLS-1$

	/**
	 * Add a service listener. The given listener will have its method called
	 * when a service is discovered.
	 * 
	 * @param listener
	 *            IServiceListener to be notified. Must not be <code>null</code>.
	 */
	public void addServiceListener(IServiceListener listener);

	/**
	 * Add a service listener. The given listener will have its method called
	 * when a service with a type matching that specified by the first parameter
	 * is discovered.
	 * 
	 * @param type
	 *            String type to listen for. Must not be <code>null</code>.
	 *            Must be formatted according to this specific IDiscoveryContainer
	 * @param listener
	 *            IServiceListener to be notified. Must not be <code>null</code>.
	 */
	public void addServiceListener(IServiceTypeID type, IServiceListener listener);

	/**
	 * Add a service type listener. The given listener will have its method
	 * called when a service type is discovered.
	 * 
	 * @param listener
	 *            the listener to be notified. Must not be <code>null</code>.
	 */
	public void addServiceTypeListener(IServiceTypeListener listener);

	/**
	 * Synchronously retrieve info about the service
	 * 
	 * @param service
	 *            IServiceID of the service to get info about. Must not be
	 *            <code>null</code>.
	 * @return IServiceInfo the service info retrieved. <code>null</code> if
	 *         no information retrievable.
	 */
	public IServiceInfo getServiceInfo(IServiceID service);

	/**
	 * Synchronously get service info about all known services
	 * 
	 * @return IServiceInfo[] the resulting array of service info instances.
	 *         Will not be <code>null</code>. May be of length 0.
	 */
	public IServiceInfo[] getServices();

	/**
	 * Synchronously get service info about all known services of given service type
	 * 
	 * @param type
	 *            IServiceTypeID defining the type of service we are interested in
	 *            getting service info about. Must not be <code>null</code>
	 * @return IServiceInfo[] the resulting array of service info instances.
	 *         Will not be <code>null</code>. May be of length 0.
	 */
	public IServiceInfo[] getServices(IServiceTypeID type);

	/**
	 * Get a Namespace for services associated with this discovery container adapter.  The given Namespace
	 * may be used via {@link ServiceIDFactory} to create IServiceIDs rather than simple IDs.  For example:
	 * <pre>
	 * IServiceID serviceID = ServiceIDFactory.getDefault().createServiceID(container.getServicesNamespace(),serviceType,serviceName);
	 * </pre>
	 * 
	 * @return Namespace for creating service IDs.  Will not be <code>null</code>.
	 */
	public Namespace getServicesNamespace();

	/**
	 * Synchronously get service info about all known services of given service type
	 * 
	 * @return IServiceTypeID[] the resulting array of service type IDs.
	 *         Will not be <code>null</code>. May be of length 0.
	 */
	public IServiceTypeID[] getServiceTypes();

	/**
	 * Register the given service. This publishes the service defined by the
	 * first parameter to the underlying publishing mechanism
	 * 
	 * @param serviceInfo
	 *            IServiceInfo of the service to be published. Must not be
	 *            <code>null</code>.
	 * @throws ECFException
	 *             if service info cannot be registered with this service
	 */
	public void registerService(IServiceInfo serviceInfo) throws ECFException;

	/**
	 * Remove a service listener. Remove the listener from this container
	 * 
	 * @param listener
	 *            IServiceListener listener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceListener(IServiceListener listener);

	/**
	 * Remove a service listener. Remove the listener associated with the type
	 * specified by the first parameter.
	 * 
	 * @param type
	 *            String of the desired type to remove the listener. Must not be
	 *            <code>null</code>.
	 *            Must be formatted according to this specific IDiscoveryContainer
	 * @param listener
	 *            IServiceListener listener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceListener(IServiceTypeID type, IServiceListener listener);

	/**
	 * Remove a service type listener. Remove the type listener.
	 * 
	 * @param listener
	 *            IServiceTypeListener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceTypeListener(IServiceTypeListener listener);

	/**
	 * Unregister a previously registered service defined by serviceInfo.
	 * 
	 * @param serviceInfo
	 *            IServiceInfo defining the service to unregister. Must not be
	 *            <code>null</code>.
	 * @throws ECFException
	 *             if service info cannot be unregistered with this service
	 */
	public void unregisterService(IServiceInfo serviceInfo) throws ECFException;
}

Back to the top