summaryrefslogtreecommitdiffstats
path: root/include/axis2_phase_resolver.h
blob: e3b1af1179f557cde292bdca551c39c45eb61632 (plain)
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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements.  See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License.  You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#ifndef AXIS2_PHASE_RESOLVER_H
#define AXIS2_PHASE_RESOLVER_H

/**
 * @defgroup axis2_phase_resolver phase resolver
 * @ingroup axis2_phase_resolver
 *
 * Engaging modules into axis2 configuration, services and operations are done here. 
 * This is accomplished mainly by following operations respectively.
 * axis2_phase_resolver_engage_module_globally().
 * axis2_phase_resolver_engage_module_to_svc().
 * axis2_phase_resolver_engage_module_to_op().
 * The user normally engage a module programmatically or using configuration files. When an
 * application client engage a module programmatically he can use axis2_op_client_engage_module()
 * function, or axis2_svc_client_engage_module() function. Engaging using configuration files means
 * adding a module_ref parameter into services.xml or axis2.xml.
 * In whatever way engaging a module finally sums upto addding module handlers into each operations flows
 * in the order defined in module.xml. Here flows in operations are actually array lists of user defined
 * phases (See op.c).
 *
 * Above functions in phase resolver add module handlers into operation flows as mentioned above as well
 * as add module handlers into system defined phases. User defined phases are added into each operation
 * at deployment time before handlers are added into them by phase resolver. System define phases
 * are added into axis2_conf_t structure and predefined handlers are added to them before module handlers
 * are added to them by phase resolver.
 *
 * Modules defined in axis2.xml are engaged by call to axis2_conf_engage_module() function. Modules defined in 
 * services xml are engaged by call to axis2_svc_enage_module() or axis2_svc_grp_engage_module(). Modules
 * define in operation tag under services.xml are engaged by call to axis2_op_engage_module() function.
 * These function in tern call one of axis2_phase_resolver_engage_module_globally() or 
 * axis2_phase_resolver_engage_module_to_svc() or axis2_phase_resolver_engage_module_to_op.
 *
 * Also when you add a service programmaticaly into axis2_conf_t you need to build execution chains for that
 * services operations.
 * axis2_phase_resolver_build_execution_chains_for_svc() is the function to be called for that purpose.
 * This will extract the already engaged modules for the configuration and service and add handlers from
 * them into operation phases.
 *
 * @{
 */

/**
 * @file axis2_phase_resolver.h
 */

#include <axis2_const.h>
#include <axutil_error.h>
#include <axis2_defines.h>
#include <axutil_env.h>
#include <axutil_allocator.h>
#include <axutil_qname.h>
#include <axutil_array_list.h>
#include <axutil_hash.h>
#include <axis2_handler_desc.h>
#include <axis2_phase.h>
#include <axis2_phase_rule.h>
#include <axis2_handler.h>
#include <axis2_handler_desc.h>
#include <axis2_flow.h>
#include <axis2_module_desc.h>
#include <axis2_phase_holder.h>

#ifdef __cplusplus
extern "C"
{
#endif

    /** Type name for axis2_phase_resolver */
    typedef struct axis2_phase_resolver axis2_phase_resolver_t;

    struct axis2_phase;
    struct axis2_handler_desc;
    struct axis2_module_desc;
    struct axis2_handler;
    struct axis2_phase_rule;
    struct axis2_svc;
    struct axis2_conf;
    struct axis2_op;
    struct axis2_phase_holder;

    /**
     * Frees phase resolver.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @return void
     */
    AXIS2_EXTERN void AXIS2_CALL
    axis2_phase_resolver_free(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env);

    /**
     * Engages the given module globally. Engaging a module globally means 
     * that the given module would be engaged to all operations in all 
     * services.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param module pointer to module
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL

    axis2_phase_resolver_engage_module_globally(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_module_desc *module);

    /**
     * Engages the given module to the given service. This means 
     * the given module would be engaged to all operations of the given 
     * service. 
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param svc pointer to service
     * @param module_desc pointer to module description
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL

    axis2_phase_resolver_engage_module_to_svc(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_svc *svc,
        struct axis2_module_desc *module_desc);

    /**
     * Engages the given module to the given operation.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param axis_op pointer to axis operation
     * @param pointer to module description
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_resolver_engage_module_to_op(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_op *axis_op,
        struct axis2_module_desc *module_desc);

    /**
     * Builds the execution chains for service. Execution chains are collection of phases that are 
     * invoked in the execution path. Execution chains for system defined phases are created when
     * call to engage_module_globally() function. Here it is created for service operations.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_resolver_build_execution_chains_for_svc(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env);

    /**
     * Builds execution chains for given module operation.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param op pointer to operation
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL

    axis2_phase_resolver_build_execution_chains_for_module_op(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_op *op);

    /**
     * Disengages the given module from the given service. This means 
     * the given module would be disengaged from all operations of the given 
     * service. 
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param svc pointer to service
     * @param module_desc pointer to module description
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_resolver_disengage_module_from_svc(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_svc *svc,
        struct axis2_module_desc *module_desc);

    /**
     * Disengages the given module from the given operation.
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @param axis_op pointer to axis operation
     * @param pointer to module description
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_resolver_disengage_module_from_op(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env,
        struct axis2_op *axis_op,
        struct axis2_module_desc *module_desc);

    /**
     * Builds transport chains. This function is no longer used in Axis2/C and hence
     * marked as deprecated.
     * @deprecated
     * @param phase_resolver pointer to phase resolver
     * @param env pointer to environment struct
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_resolver_build_transport_chains(
        axis2_phase_resolver_t * phase_resolver,
        const axutil_env_t * env);

    /**
     * Creates phase resolver struct.
     * @param env pointer to environment struct
     * @return pointer to newly created phase resolver
     */
    AXIS2_EXTERN axis2_phase_resolver_t *AXIS2_CALL

    axis2_phase_resolver_create(
        const axutil_env_t * env);

    /**
     * Creates phase resolver struct with given configuration.
     * @param env pointer to environment struct
     * @param axis2_config pointer to aixs2 configuration, phase resolver 
     * created would not assume ownership of configuration
     * @return pointer to newly created phase resolver
     */
    AXIS2_EXTERN axis2_phase_resolver_t *AXIS2_CALL

    axis2_phase_resolver_create_with_config(
        const axutil_env_t * env,
        struct axis2_conf *axis2_config);

    /**
     * Creates phase resolver struct with given configuration and service.
     * @param env pointer to environment struct
     * @param aixs2_config pointer to aixs2 configuration,  phase resolver 
     * created would not assume ownership of configuration
     * @param svc pointer to service,  phase resolver 
     * created would not assume ownership of service
     * @return pointer to newly created phase resolver
     */
    AXIS2_EXTERN axis2_phase_resolver_t *AXIS2_CALL

    axis2_phase_resolver_create_with_config_and_svc(
        const axutil_env_t * env,
        struct axis2_conf *axis2_config,
        struct axis2_svc *svc);

    /** @} */

#ifdef __cplusplus
}
#endif
#endif                          /* AXIS2_PHASE_RESOLVER_H */