1//
2// Copyright (c) ZeroC, Inc. All rights reserved.
3//
4
5#pragma once
6
7[["ice-prefix", "cpp:header-ext:h"]]
8
9#include <Ice/Identity.ice>
10#include <Ice/BuiltinSequences.ice>
11#include <Ice/ProcessF.ice>
12#include <Ice/Properties.ice>
13
14#include <Glacier2/Session.ice>
15#include <IceGrid/Admin.ice>
16#include <IceGrid/Registry.ice>
17
18module IceGrid
19{
20
21local exception SynchronizationException
22{
23}
24
25class InternalDbEnvDescriptor
26{
27    /** The name of the database environment. */
28    string name;
29
30    /** The database properties. */
31    PropertyDescriptorSeq properties;
32}
33sequence<InternalDbEnvDescriptor> InternalDbEnvDescriptorSeq;
34
35class InternalAdapterDescriptor
36{
37    /** The identifier of the server. */
38    string id;
39
40    /** Specifies if the lifetime of the adapter is the same as the server. */
41    bool serverLifetime;
42}
43sequence<InternalAdapterDescriptor> InternalAdapterDescriptorSeq;
44
45class InternalDistributionDescriptor
46{
47    /** The proxy of the IcePatch2 server. */
48    string icepatch;
49
50    /** The source directories. */
51    ["java:type:java.util.LinkedList<String>"] Ice::StringSeq directories;
52}
53
54dictionary<string, PropertyDescriptorSeq> PropertyDescriptorSeqDict;
55
56class InternalServerDescriptor
57{
58    /** The server ID. */
59    string id;
60
61    /** The server application */
62    string application;
63
64    /** The application uuid. */
65    string uuid;
66
67    /** The application revision. */
68    int revision;
69
70    /** The id of the session which allocated the server. */
71    string sessionId;
72
73    /** The server executable. */
74    string exe;
75
76    /** The server working directory. */
77    string pwd;
78
79    /** The user ID to use to run the server. */
80    string user;
81
82    /** The server activation mode. */
83    string activation;
84
85    /** The server activation timeout. */
86    string activationTimeout;
87
88    /** The server deactivation timeout. */
89    string deactivationTimeout;
90
91    /** Specifies if the server depends on the application distrib. */
92    bool applicationDistrib;
93
94    /** The distribution descriptor of this server. */
95    InternalDistributionDescriptor distrib;
96
97    /** Specifies if a process object is registered. */
98    bool processRegistered;
99
100    /** The server command line options. */
101    Ice::StringSeq options;
102
103    /** The server environment variables. */
104    Ice::StringSeq envs;
105
106    /** The path of the server logs. */
107    Ice::StringSeq logs;
108
109    /** The indirect object adapters. */
110    InternalAdapterDescriptorSeq adapters;
111
112    /** The database environments. */
113    InternalDbEnvDescriptorSeq dbEnvs;
114
115    /** The configuration files of the server. */
116    PropertyDescriptorSeqDict properties;
117
118    /** IceBox service names */
119    optional(1) Ice::StringSeq services;
120}
121
122/**
123 *
124 * This exception is raised if an adapter is active.
125 *
126 **/
127exception AdapterActiveException
128{
129}
130
131exception AdapterNotActiveException
132{
133    /** True if the adapter can be activated on demand. */
134    bool activatable;
135}
136
137interface Adapter
138{
139    /**
140     *
141     * Activate this adapter. If this adapter can be activated, this
142     * will activate the adapter and return the direct proxy of the
143     * adapter once it's active. If this adapter can be activated on
144     * demand, this will return 0 if the adapter is inactive or the
145     * adapter direct proxy it's active.
146     *
147     **/
148    ["amd"] Object* activate();
149
150    /**
151     *
152     * Get the adapter direct proxy. The adapter direct proxy is a
153     * proxy created with the object adapter. The proxy contains the
154     * last known adapter endpoints.
155     *
156     * @return A direct proxy containing the last known adapter
157     * endpoints if the adapter is already active.
158     *
159     **/
160    ["nonmutating", "cpp:const"] idempotent Object* getDirectProxy()
161        throws AdapterNotActiveException;
162
163    /**
164     *
165     * Set the direct proxy for this adapter.
166     *
167     * @param The direct proxy. The direct proxy should be created
168     * with the object adapter and should contain the object adapter
169     * endpoints.
170     *
171     * @throws AdapterActiveException The adapter is already
172     * active. It's not possible to override the direct proxy of an
173     * active adapter.
174     *
175     **/
176    void setDirectProxy(Object* proxy)
177        throws AdapterActiveException;
178}
179
180/**
181 *
182 * This exception is raised if an adapter with the same name already
183 * exists.
184 *
185 **/
186exception AdapterExistsException
187{
188    string id;
189}
190
191dictionary<string, Adapter*> AdapterPrxDict;
192
193interface FileReader
194{
195    /**
196     *
197     * Count the number of given lines from the end of the file and
198     * return the file offset.
199     *
200     **/
201    ["cpp:const"] idempotent long getOffsetFromEnd(string filename, int lines)
202        throws FileNotAvailableException;
203
204    /**
205     *
206     * Read lines (or size bytes) at the specified position from the given file.
207     *
208     **/
209    ["cpp:const"] idempotent bool read(string filename, long pos, int size, out long newPos, out Ice::StringSeq lines)
210        throws FileNotAvailableException;
211}
212
213interface Server extends FileReader
214{
215    /**
216     *
217     * Start the server.
218     *
219     * @return True if the server was successfully started, false
220     * otherwise.
221     *
222     **/
223    ["amd"] void start()
224        throws ServerStartException;
225
226    /**
227     *
228     * Stop the server. This methods returns only when the server is
229     * deactivated. If the server doesn't stop after a configurable
230     * amount of time, it will be killed.
231     *
232     **/
233    ["amd"] void stop()
234        throws ServerStopException;
235
236    /**
237     *
238     * Check if the given server can be loaded on this node.
239     *
240     * @return True if the server is inactive.
241     *
242     * @throws DeploymentException Raised if the server can't be updated.
243     *
244     **/
245    bool checkUpdate(InternalServerDescriptor svr, bool noRestart)
246        throws DeploymentException;
247
248    /**
249     *
250     * Enable or disable the server.
251     *
252     **/
253    void setEnabled(bool enable);
254
255    /**
256     *
257     * Check if the server is enabled.
258     *
259     **/
260    ["nonmutating", "cpp:const"] idempotent bool isEnabled();
261
262    /**
263     *
264     * Send signal to the server
265     *
266     **/
267    void sendSignal(string signal)
268        throws BadSignalException;
269
270    /**
271     *
272     * Write message on servers' stdout or stderr.
273     *
274     **/
275    void writeMessage(string message, int fd);
276
277    /**
278     *
279     * Return the server state.
280     *
281     * @return The server state.
282     *
283     * @see ServerState
284     *
285     **/
286    ["nonmutating", "cpp:const"] idempotent ServerState getState();
287
288    /**
289     *
290     * Get the server pid. Note that the value returned by this method
291     * is system dependant. On Unix operating systems, it's the pid
292     * value returned by the fork() system call and converted to an
293     * integer.
294     *
295     **/
296    ["nonmutating", "cpp:const"] idempotent int getPid();
297
298    /**
299     *
300     * Set the process proxy.
301     *
302     **/
303    ["amd"] void setProcess(Ice::Process* proc);
304}
305
306interface InternalRegistry;
307sequence<InternalRegistry*> InternalRegistryPrxSeq;
308
309interface ReplicaObserver
310{
311    /**
312     *
313     * Initialization of the replica observer.
314     *
315     **/
316    void replicaInit(InternalRegistryPrxSeq replicas);
317
318    /**
319     *
320     * Notification that a replica has been added. The node should
321     * establish a session with this new replica.
322     *
323     **/
324    void replicaAdded(InternalRegistry* replica);
325
326    /**
327     *
328     * Notification that a replica has been removed. The node should
329     * destroy the session to this replica.
330     *
331     **/
332    void replicaRemoved(InternalRegistry* replica);
333}
334
335interface PatcherFeedback
336{
337    /**
338     *
339     * The patch completed successfully.
340     *
341     **/
342    void finished();
343
344    /**
345     *
346     * The patch on the given node failed for the given reason.
347     *
348     **/
349    void failed(string reason);
350}
351
352interface Node extends FileReader, ReplicaObserver
353{
354    /**
355     *
356     * Load the given server. If the server resources weren't already
357     * created (database environment directories, property files, etc),
358     * they will be created.
359     *
360     **/
361    ["amd"] idempotent Server* loadServer(InternalServerDescriptor svr,
362                                                 string replicaName,
363                                                 out AdapterPrxDict adapters,
364                                                 out int actTimeout,
365                                                 out int deactTimeout)
366        throws DeploymentException;
367
368    /**
369     *
370     * Load the given server and ensure the server won't be
371     * restarted. If the server resources weren't already created
372     * (database environment directories, property files, etc), they
373     * will be created. If the server can't be updated without a
374     * restart, a DeploymentException is raised.
375     *
376     **/
377    ["amd"] idempotent Server* loadServerWithoutRestart(InternalServerDescriptor svr,
378                                                        string replicaName,
379                                                        out AdapterPrxDict adapters,
380                                                        out int actTimeout,
381                                                        out int deactTimeout)
382        throws DeploymentException;
383
384    /**
385     *
386     * Destroy the given server.
387     *
388     **/
389    ["amd"] idempotent void destroyServer(string name, string uuid, int revision, string replicaName)
390        throws DeploymentException;
391
392    /**
393     *
394     * Destroy the server if it's not active.
395     *
396     **/
397    ["amd"] idempotent void destroyServerWithoutRestart(string name, string uuid, int revision, string replicaName)
398        throws DeploymentException;
399
400    /**
401     *
402     * Patch application and server distributions. If some servers
403     * using a distribution directory to patch are active, this method
404     * will raise a PatchException unless shutdown is set to true. In
405     * which case the servers will be shutdown.
406     *
407     **/
408    ["amd"] idempotent void patch(PatcherFeedback* feedback,
409                                  string application,
410                                  string server,
411                                  InternalDistributionDescriptor appDistrib,
412                                  bool shutdown);
413
414    /**
415     *
416     * Establish a session to the given replica, this method only
417     * returns once the registration was attempted (unlike
418     * replicaAdded below).
419     *
420     **/
421    void registerWithReplica(InternalRegistry* replica);
422
423    /**
424     *
425     * Get the node name.
426     *
427     **/
428    ["nonmutating", "cpp:const"] idempotent string getName();
429
430    /**
431     *
432     * Get the node hostname.
433     *
434     **/
435    ["nonmutating", "cpp:const"] idempotent string getHostname();
436
437    /**
438     *
439     * Get the node load.
440     *
441     **/
442    ["nonmutating", "cpp:const"] idempotent LoadInfo getLoad();
443
444    /**
445     *
446     * Get the number of processor sockets for the machine where this
447     * node is running.
448     *
449     **/
450    ["nonmutating", "cpp:const"] idempotent int getProcessorSocketCount();
451
452    /**
453     *
454     * Shutdown the node.
455     *
456     **/
457    ["nonmutating", "cpp:const"] idempotent void shutdown();
458}
459
460sequence<Node*> NodePrxSeq;
461
462/**
463 *
464 * This exception is raised if a node is already registered and
465 * active.
466 *
467 **/
468exception NodeActiveException
469{
470}
471
472interface NodeSession
473{
474    /**
475     *
476     * The node call this method to keep the session alive.
477     *
478     **/
479    void keepAlive(LoadInfo load);
480
481    /**
482     *
483     * Set the replica observer. The node calls this method when it's
484     * ready to receive notifications for the replicas. It only calls
485     * this for the session with the master.
486     *
487     **/
488    void setReplicaObserver(ReplicaObserver* observer);
489
490    /**
491     *
492     * Return the node session timeout.
493     *
494     **/
495    ["nonmutating", "cpp:const"] idempotent int getTimeout();
496
497    /**
498     *
499     * Return the node observer.
500     *
501     **/
502    ["nonmutating", "cpp:const"] idempotent NodeObserver* getObserver();
503
504    /**
505     *
506     * Ask the registry to load the servers on the node.
507     *
508     **/
509    ["amd", "nonmutating", "cpp:const"] idempotent void loadServers();
510
511    /**
512     *
513     * Get the name of the servers deployed on the node.
514     *
515     **/
516    ["nonmutating", "cpp:const"] idempotent Ice::StringSeq getServers();
517
518    /**
519     *
520     * Wait for the application update to complete (the application is
521     * completely updated once all the registry replicas have been
522     * updated). This is used by the node to ensure that before to
523     * start a server all the replicas have the up-to-date descriptor
524     * of the server.
525     *
526     **/
527    ["amd", "cpp:const"] void waitForApplicationUpdate(string application, int revision);
528
529    /**
530     *
531     * Destroy the session.
532     *
533     **/
534    void destroy();
535}
536
537/**
538 *
539 * This exception is raised if a replica is already registered and
540 * active.
541 *
542 **/
543exception ReplicaActiveException
544{
545}
546
547enum TopicName
548{
549    RegistryObserverTopicName,
550    NodeObserverTopicName,
551    ApplicationObserverTopicName,
552    AdapterObserverTopicName,
553    ObjectObserverTopicName
554}
555
556interface DatabaseObserver extends ApplicationObserver, ObjectObserver, AdapterObserver
557{
558}
559
560dictionary<string, long> StringLongDict;
561
562interface ReplicaSession
563{
564    /**
565     *
566     * The replica call this method to keep the session alive.
567     *
568     **/
569    void keepAlive();
570
571    /**
572     *
573     * Return the replica session timeout.
574     *
575     **/
576    ["cpp:const"] idempotent int getTimeout();
577
578    /**
579     *
580     * Set the database observer. Once the observer is subscribed, it
581     * will receive the database and database updates.
582     *
583     **/
584    idempotent void setDatabaseObserver(DatabaseObserver* dbObs, optional(1) StringLongDict serials)
585        throws ObserverAlreadyRegisteredException, DeploymentException;
586
587    /**
588     *
589     * This method sets the endpoints of the replica. This allows the
590     * master to create proxies with multiple endpoints for replicated
591     * objects (e.g.: IceGrid::Query object).
592     *
593     **/
594    idempotent void setEndpoints(StringObjectProxyDict endpoints);
595
596    /**
597     *
598     * Registers the replica well-known objects with the master.
599     *
600     **/
601    idempotent void registerWellKnownObjects(ObjectInfoSeq objects);
602
603    /**
604     *
605     * Set the adapter direct proxy of the given adapter in the
606     * master. This is used to support dynamic registration with
607     * the locator registry interface.
608     *
609     **/
610    idempotent void setAdapterDirectProxy(string adapterId, string replicaGroupId, Object* proxy)
611        throws AdapterNotExistException, AdapterExistsException;
612
613    /**
614     *
615     * Notify the master that an update was received. The master might
616     * wait for replication updates to be received by all the replicas
617     * before to continue.
618     *
619     **/
620    void receivedUpdate(TopicName name, int serial, string failure);
621
622    /**
623     *
624     * Destroy the session.
625     *
626     **/
627    void destroy();
628}
629
630/**
631 *
632 * Information about an IceGrid node.
633 *
634 **/
635class InternalNodeInfo
636{
637    /**
638     *
639     * The name of the node.
640     *
641     **/
642    string name;
643
644    /**
645     *
646     * The operating system name.
647     *
648     **/
649    string os;
650
651    /**
652     *
653     * The network name of the host running this node (as defined in
654     * uname()).
655     *
656     **/
657    string hostname;
658
659    /**
660     *
661     * The operation system release level (as defined in uname()).
662     *
663     **/
664    string release;
665
666    /**
667     *
668     * The operation system version (as defined in uname()).
669     *
670     **/
671    string version;
672
673    /**
674     *
675     * The machine hardware type (as defined in uname()).
676     *
677     **/
678    string machine;
679
680    /**
681     *
682     * The number of processor threads (e.g. 8 on
683     * system with 1 quad-core CPU, with 2 threads per core)
684     *
685     **/
686    int nProcessors;
687
688    /**
689     *
690     * The path to the node data directory.
691     *
692     **/
693    string dataDir;
694}
695
696/**
697 *
698 * Information about an IceGrid registry replica.
699 *
700 **/
701class InternalReplicaInfo
702{
703    /**
704     *
705     * The name of the registry.
706     *
707     **/
708    string name;
709
710    /**
711     *
712     * The network name of the host running this registry (as defined in
713     * uname()).
714     *
715     **/
716    string hostname;
717}
718
719interface InternalRegistry extends FileReader
720{
721    /**
722     *
723     * Register a node with the registry. If a node with the same name
724     * is already registered, [registerNode] will overide the previous
725     * node only if it's not active.
726     *
727     * @param info Some information on the node.
728     *
729     * @param prx The proxy of the node.
730     *
731     * @param loadInf The load information of the node.
732     *
733     * @return The node session proxy.
734     *
735     * @throws NodeActiveException Raised if the node is already
736     * registered and currently active.
737     *
738     **/
739    NodeSession* registerNode(InternalNodeInfo info, Node* prx, LoadInfo loadInf)
740        throws NodeActiveException, PermissionDeniedException;
741
742    /**
743     *
744     * Register a replica with the registry. If a replica with the
745     * same name is already registered, [registerReplica] will overide
746     * the previous replica only if it's not active.
747     *
748     * @param info Some information on the replica.
749     *
750     * @param prx The proxy of the replica.
751     *
752     * @return The replica session proxy.
753     *
754     * @throws ReplicaActiveException Raised if the replica is already
755     * registered and currently active.
756     *
757     **/
758    ReplicaSession* registerReplica(InternalReplicaInfo info, InternalRegistry* prx)
759        throws ReplicaActiveException, PermissionDeniedException;
760
761    /**
762     *
763     * Create a session with the given registry replica. This method
764     * returns only once the session creation has been attempted.
765     *
766     **/
767    void registerWithReplica(InternalRegistry* prx);
768
769    /**
770     *
771     * Return the proxies of all the nodes known by this registry.
772     *
773     **/
774    ["cpp:const"] idempotent NodePrxSeq getNodes();
775
776    /**
777     *
778     * Return the proxies of all the registry replicas known by this
779     * registry.
780     *
781     **/
782    ["cpp:const"] idempotent InternalRegistryPrxSeq getReplicas();
783
784    /**
785     *
786     * Return applications, adapters, objects from this replica.
787     *
788     **/
789    ["cpp:const"] idempotent ApplicationInfoSeq getApplications(out long serial);
790    ["cpp:const"] idempotent AdapterInfoSeq getAdapters(out long serial);
791    ["cpp:const"] idempotent ObjectInfoSeq getObjects(out long serial);
792
793    /**
794     *
795     * Shutdown this registry.
796     *
797     **/
798    ["cpp:const"] idempotent void shutdown();
799}
800
801}
802