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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
// **********************************************************************
//
// Copyright (c) 2002
// ZeroC, Inc.
// Huntsville, AL, USA
//
// All Rights Reserved
//
// **********************************************************************
#ifndef ICE_BOX_ICE_BOX_ICE
#define ICE_BOX_ICE_BOX_ICE
#include <Ice/BuiltinSequences.ice>
#include <Ice/CommunicatorF.ice>
#include <Ice/PropertiesF.ice>
#include <Freeze/DB.ice>
module IceBox
{
/**
*
* Used to indicate failure. For example, if a service encounters
* an error during initialization, or if the service manager is
* unable to load a service executable.
*
**/
local exception FailureException
{
/**
*
* The reason for the failure.
*
**/
string reason;
};
/**
*
* Base interface for an application service managed by a [ServiceManager].
* The * [ServiceManager] will invoke [init] on all services prior to
* calling [start], and will invoke [stop] on all services when
* [ServiceManager::shutdown] is called. The order in which the
* services are invoked is not defined. The service lifecycle
* operations are described below:
*
* <itemizedlist>
*
* <listitem><para>[init] - This is the opportunity for the service to
* create a Communicator or object adapter, register servants,
* etc.</para></listitem>
*
* <listitem><para>[start] - Perform any client-side activities which
* might result in an invocation on a collocated service.
* </para></listitem>
*
* <listitem><para>[stop] - Destroy Communicators, deactivate Object
* Adapters, clean up resources, etc. The [ServiceManager] guarantees
* that [stop] will be invoked on all services whose [init] has been
* invoked.</para></listitem>
*
* </itemizedlist>
*
* <note><para>If the service requires an object adapter, it should be
* created and activated in [init]. However, the service should
* refrain from any client-side activities which might result in an
* invocation on a collocated service, because the order of service
* configuration is not defined and therefore the target service may
* not be active yet. Client-side activities can be safely performed
* in [start], as the [ServiceManager] guarantees that all services
* will be configured before [start] is invoked. </para></note>
*
* @see ServiceManager
* @see Service
* @see FreezeService
*
**/
local interface ServiceBase
{
/**
*
* Stop the service.
*
**/
void stop();
#if 0
//
// Potential future operations
//
Ice::StringSeq getParameters() throws ServiceNotExist; // Need better return type
void setParameter(string param, string value) throws FailureException; // Use a different except?
#endif
};
/**
*
* A standard application service managed by a [ServiceManager].
*
* @see ServiceBase
*
**/
local interface Service extends ServiceBase
{
/**
*
* Initialize the service. The given Communicator is created by
* the [ServiceManager]. It may be shared by other services
* depending on the service configuration.
*
* <note><para>The [ServiceManager] owns this Communicator, and is
* responsible for destroying it.</para></note>
*
* @param name The service's name, as determined by the
* configuration.
*
* @param communicator The [ServiceManager]'s Communicator
* instance.
*
* @param args The service arguments which were not converted into
* properties.
*
* @throws FailureException Raised if [init] failed.
*
* @see start
*
**/
void start(string name, Ice::Communicator communicator, Ice::StringSeq args)
throws FailureException;
};
/**
*
* A Freeze application service managed by the [ServiceManager]. It takes
* care of the the initialization and shutdown of the Freeze database for
* the application.
*
* @see ServiceBase
*
*/
local interface FreezeService extends ServiceBase
{
/**
*
* Initialize the service. The given Communicator is created by
* the [ServiceManager]. It may be shared by other services
* depending on the service configuration.
*
* <note><para>The [ServiceManager] owns this Communicator, and is
* responsible for destroying it.</para></note>
*
* @param name The service's name, as determined by the
* configuration.
*
* @param communicator The [ServiceManager]'s Communicator
* instance.
*
* @param args The service arguments which were not converted into
* properties.
*
* @param dbEnv The Freeze database environment.
*
* @throws FailureException Raised if [init] failed.
*
* @see ServiceBase
*
**/
void start(string name, Ice::Communicator communicator, Ice::StringSeq args, Freeze::DBEnvironment dbEnv)
throws FailureException;
};
/**
*
* Administers a set of [Service] instances.
*
* @see Service
*
**/
interface ServiceManager
{
/**
*
* Shutdown all services. This will cause [Service::stop] to be
* invoked on all configured services.
*
**/
// ML: I don't like the name shutdown. Shouldn't this be stopAll(), as below?
void shutdown();
#if 0
//
// Potential future operations
//
Ice::StringSeq getServices();
void start(string service, string exec, Ice::StringSeq args) throws FailureException;
void stop(string service) throws ServiceNotExist; // Allow service to override this?
void stopAll();
Ice::StringSeq getParameters(string service) throws ServiceNotExist; // Need better return type
void setParameter(string service, string param, string value) throws ServiceNotExist, FailureException; // Use a different except?
#endif
};
};
#endif
|
