Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: afa0b58b5d083ccefabe23b7f7e39140d8216961 (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
/*******************************************************************************
* Copyright (c) 2010 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.server.generic;

import java.io.IOException;
import java.net.URI;
import java.util.Map;
import org.eclipse.ecf.core.ContainerCreateException;
import org.eclipse.ecf.core.IContainer;
import org.eclipse.ecf.core.sharedobject.ISharedObjectContainer;

/**
 * Generic server container group.  Instances of this type are returned from using the {@link IGenericServerContainerGroupFactory}
 * service.
 * 
 * @since 4.0
 */
public interface IGenericServerContainerGroup {

	public static final int DEFAULT_KEEPALIVE = 30000;

	/**
	 * Get the URI for the group endpoint.  For
	 * @return uri that is the group endpoint.  For example uri='ecftcp://localhost:3282'
	 */
	public URI getGroupEndpoint();

	/**
	 * Create a shared object container within this container group, given a path, a keepAlive value, and a Map of properties
	 * that will be provided to the created container.
	 * 
	 * @param path the uri path suffix for defining the container's identity.  For example, if {@link #getGroupEndpoint()}
	 * returns 'ecftcp://localhost:3282', and a path of '/server' is used to create a new container, then the container's id
	 * will be 'ecftcp://localhost:3282/server'.  Must not be <code>null</code>.
	 * @param keepAlive a value (in milliseconds) that defines the keepAlive for the resulting container.
	 * @param properties to be associated to the returned container upon instantiation.
	 * @return shared object container.  Will not be <code>null</code>.
	 * @throws ContainerCreateException if container with given path, keepAlive, and properties could not be created.
	 */
	public ISharedObjectContainer createContainer(String path, int keepAlive, Map properties) throws ContainerCreateException;

	/**
	 * Create a shared object container within this container group, given a path, a keepAlive value, and a Map of properties
	 * that will be provided to the created container.
	 * 
	 * @param path the uri path suffix for defining the container's identity.  For example, if {@link #getGroupEndpoint()}
	 * returns 'ecftcp://localhost:3282', and a path of '/server' is used to create a new container, then the container's id
	 * will be 'ecftcp://localhost:3282/server'.  Must not be <code>null</code>.
	 * @param keepAlive a value (in milliseconds) that defines the keepAlive for the resulting container.
	 * @return shared object container.  Will not be <code>null</code>.
	 * @throws ContainerCreateException if container with given path, keepAlive, and properties could not be created.
	 * @since 5.0
	 */
	public ISharedObjectContainer createContainer(String path, int keepAlive) throws ContainerCreateException;

	/**
	 * Create a shared object container within this container group, given a path, a keepAlive value, and a Map of properties
	 * that will be provided to the created container.
	 * 
	 * @param path the uri path suffix for defining the container's identity.  For example, if {@link #getGroupEndpoint()}
	 * returns 'ecftcp://localhost:3282', and a path of '/server' is used to create a new container, then the container's id
	 * will be 'ecftcp://localhost:3282/server'.  Must not be <code>null</code>.
	 * @return shared object container.  Will not be <code>null</code>.
	 * @throws ContainerCreateException if container with given path, keepAlive, and properties could not be created.
	 * @since 5.0
	 */
	public ISharedObjectContainer createContainer(String path) throws ContainerCreateException;

	/**
	 * Get the container instance associated with the given path. 
	 * 
	 * @param path of the container to return.  Must not be <code>null</code>.
	 * @return the previously created shared object container associated with the given path.
	 */
	public ISharedObjectContainer getContainer(String path);

	/**
	 * Get a map (String->ISharedObjectContainer) of the path->containers previously created.
	 * @return map of the path->container map for this generic server container group.  Will not return <code>null</code>, but
	 * may return a Map of size==0.
	 */
	public Map getContainers();

	/**
	 * Remove previously created container with given path.
	 * 
	 * @param path of the shared object container to remove.
	 * @return shared object container removed.  If no shared object container was previously created
	 * with the given path, then <code>null</code> will be returned.
	 */
	public ISharedObjectContainer removeContainer(String path);

	/**
	 * Start listening on the port given to this generic server container group upon creation.
	 * 
	 * @throws IOException if the server port cannot be opened for listening.
	 * 
	 * @see IGenericServerContainerGroupFactory#createContainerGroup(String, int, Map)
	 */
	public void startListening() throws IOException;

	/**
	 * Returns <code>true</code> if this container group previously started listening via a successful call to {@link #startListening()}).
	 * 
	 * @return <code>true</code> if currently listening, <code>false</code> otherwise.
	 */
	public boolean isListening();

	/**
	 * Stop listening on port given to this generic server container group upon creation.
	 */
	public void stopListening();

	/**
	 * Close this generic server container group.  This method will:
	 * <ol>
	 * <li>iterate through all containers created via {@link #createContainer(String, int, Map)} within this group, and for each one:</li>
	 * <ol>
	 *   <li>remove it from the set of containers within this group</li>
	 *   <li>call {@link IContainer#dispose()}</li>
	 * </ol>
	 * <li>stop listening on the port given to this generic server container group upon creation.</li>
	 * </ol>
	 */
	public void close();
}

Back to the top