2
* Copyright 1999-2004 The Apache Software Foundation
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
17
/***************************************************************************
18
* Description: Definitions of the objects used during the service step. *
19
* These are the web server (ws) the worker and the connection*
20
* JVM connection point *
21
* Author: Gal Shachor <shachor@il.ibm.com> *
22
* Author: Dan Milstein <danmil@shore.net> *
23
* Author: Henri Gomez <hgomez@apache.org> *
24
* Version: $Revision: 1.32 $ *
25
***************************************************************************/
30
#include "jk_global.h"
31
#include "jk_logger.h"
34
#include "jk_uri_worker_map.h"
35
#include "jk_msg_buff.h"
42
#endif /* __cplusplus */
45
* Env Information to be provided to worker at init time
46
* With AJP14 support we need to have access to many informations
47
* about web-server, uri to worker map....
53
/* The URI to WORKER map, will be feeded by AJP14 autoconf feature */
54
jk_uri_worker_map_t *uri_to_worker;
56
unsigned int num_of_workers;
59
/* Web-Server we're running on (Apache/IIS/NES) */
62
/* Virtual server handled - "*" is all virtual */
65
typedef struct jk_worker_env jk_worker_env_t;
70
typedef struct jk_ws_service jk_ws_service_t;
71
typedef struct jk_endpoint jk_endpoint_t;
72
typedef struct jk_worker jk_worker_t;
75
* The web server service 'class'. An instance of this class is created
76
* for each request which is forwarded from the web server to the servlet
77
* container. Contains the basic information about the request
78
* (e.g. protocol, req_uri, etc), and also contains a series of methods
79
* which provide access to core web server functionality (start_response,
80
* read, write). This class might be more accurately called ws_request.
82
* As with all the core jk classes, this is essentially an abstract base
83
* class which is implemented/extended by classes which are specific to a
84
* particular web server. By using an abstract base class in this manner,
85
* workers can be written for different protocols (e.g. ajp12, ajp13, ajp14)
86
* without the workers having to worry about which web server they are
89
* This particular OO-in-C system uses a 'ws_private' pointer to point to
90
* the platform-specific data. So in the subclasses, the methods do most
91
* of their work by getting their hands on the ws_private pointer and then
92
* using that to get at the correctly formatted data and functions for
95
* Try imagining this as a 'public abstract class', and the ws_private
96
* pointer as a sort of extra 'this' reference. Or imagine that you are
97
* seeing the internal vtables of your favorite OO language. Whatever
100
* See apache1.3/mod_jk.c and iis/jk_isapi_plugin.c for examples.
106
* A 'this' pointer which is used by the subclasses of this class to
107
* point to data which is specific to a given web server platform
108
* (e.g. Apache or IIS).
113
* Provides memory management. All data specific to this request is
114
* allocated within this pool, which can then be reclaimed at the end
115
* of the request handling cycle.
117
* Alive as long as the request is alive.
122
* CGI Environment needed by servlets
125
const char *protocol;
127
const char *remote_addr;
128
const char *remote_host;
129
const char *remote_user;
130
const char *auth_type;
131
const char *query_string;
132
const char *server_name;
133
unsigned server_port;
134
char *server_software;
135
unsigned content_length; /* integer that represents the content */
136
/* length should be 0 if unknown. */
137
unsigned is_chunked; /* 1 if content length is unknown (chunked rq) */
138
unsigned no_more_chunks; /* 1 if last chunk has been read */
139
unsigned content_read; /* number of bytes read */
144
* is_ssl - True if request is in ssl connection
145
* ssl_cert - If available, base64 ASN.1 encoded client certificates.
146
* ssl_cert_len - Length of ssl_cert, 0 if certificates are not available.
147
* ssl_cipher - The ssl cipher suite in use.
148
* ssl_session - The ssl session string
150
* In some servers it is impossible to extract all this information, in this
151
* case, we are passing NULL.
155
unsigned ssl_cert_len;
160
* SSL extra information for Servlet 2.3 API
162
* ssl_key_size - ssl key size in use
167
* Headers, names and values.
169
char **headers_names; /* Names of the request headers */
170
char **headers_values; /* Values of the request headers */
171
unsigned num_headers; /* Number of request headers */
175
* Request attributes.
177
* These attributes that were extracted from the web server and are
180
* The developer should be able to read them from the ServletRequest
181
* attributes. Tomcat is required to append org.apache.tomcat. to
182
* these attrinbute names.
184
char **attributes_names; /* Names of the request attributes */
185
char **attributes_values; /* Values of the request attributes */
186
unsigned num_attributes; /* Number of request attributes */
189
* The jvm route is in use when the adapter load balance among
190
* several JVMs. It is the ID of a specific JVM in the load balance
191
* group. We are using this variable to implement JVM session
194
const char *jvm_route;
196
/* Temp solution for auth. For native1 it'll be sent on each request,
197
if an option is present. For native2 it'll be sent with the first
198
request. On java side, both cases will work. For tomcat3.2 or
199
a version that doesn't support secret - don't set the secret,
204
* Callbacks into the web server. For each, the first argument is
205
* essentially a 'this' pointer. All return JK_TRUE on success
206
* and JK_FALSE on failure.
210
* Area to get POST data for fail-over recovery in POST
212
jk_msg_buf_t *reco_buf;
215
/* Number of retries. Defaults to JK_RETRIES
220
* If set call flush after each write
224
/* Uri worker map. Added for virtual host support
226
jk_uri_worker_map_t *uw_map;
229
* Send the response headers to the browser.
231
int (JK_METHOD * start_response) (jk_ws_service_t *s,
234
const char *const *header_names,
235
const char *const *header_values,
236
unsigned num_of_headers);
239
* Read a chunk of the request body into a buffer. Attempt to read len
240
* bytes into the buffer. Write the number of bytes actually read into
243
int (JK_METHOD * read) (jk_ws_service_t *s,
245
unsigned len, unsigned *actually_read);
248
* Write a chunk of response data back to the browser.
250
int (JK_METHOD * write) (jk_ws_service_t *s,
251
const void *buffer, unsigned len);
254
* Flush a chunk of response data back to the browser.
256
void (JK_METHOD * flush) (jk_ws_service_t *s);
260
* The endpoint 'class', which represents one end of a connection to the
261
* servlet engine. Basically, supports nothing other than forwarding the
262
* request to the servlet engine. Endpoints can be persistent (as with
263
* ajp13/ajp14, where a single connection is reused many times), or can last for a
264
* single request (as with ajp12, where a new connection is created for
267
* An endpoint for a given protocol is obtained by the web server plugin
268
* from a worker object for that protocol. See below for details.
270
* As with all the core jk classes, this is essentially an abstract base
271
* class which is implemented/extended by classes which are specific to a
272
* particular protocol. By using an abstract base class in this manner,
273
* plugins can be written for different servers (e.g. IIS, Apache) without
274
* the plugins having to worry about which protocol they are talking.
276
* This particular OO-in-C system uses a 'endpoint_private' pointer to
277
* point to the protocol-specific data/functions. So in the subclasses, the
278
* methods do most of their work by getting their hands on the
279
* endpoint_private pointer and then using that to get at the functions for
282
* Try imagining this as a 'public abstract class', and the
283
* endpoint_private pointer as a sort of extra 'this' reference. Or
284
* imagine that you are seeing the internal vtables of your favorite OO
285
* language. Whatever works for you.
287
* See jk_ajp13_worker.c/jk_ajp14_worker.c and jk_ajp12_worker.c for examples.
295
* A 'this' pointer which is used by the subclasses of this class to
296
* point to data/functions which are specific to a given protocol
297
* (e.g. ajp12 or ajp13 or ajp14).
299
void *endpoint_private;
302
* Forward a request to the servlet engine. The request is described
303
* by the jk_ws_service_t object.
304
* is_error is either 0 meaning recoverable or set to
305
* the HTTP error code.
307
int (JK_METHOD * service) (jk_endpoint_t *e,
309
jk_logger_t *l, int *is_error);
312
* Called when this particular endpoint has finished processing a
313
* request. For some protocols (e.g. ajp12), this frees the memory
314
* associated with the endpoint. For others (e.g. ajp13/ajp14), this can
315
* return the endpoint to a cache of already opened endpoints.
317
* Note that the first argument is *not* a 'this' pointer, but is
318
* rather a pointer to a 'this' pointer. This is necessary, because
319
* we may need to free this object.
321
int (JK_METHOD * done) (jk_endpoint_t **p, jk_logger_t *l);
325
* The worker 'class', which represents something to which the web server
326
* can delegate requests.
328
* This can mean communicating with a particular servlet engine instance,
329
* using a particular protocol. A single web server instance may have
330
* multiple workers communicating with a single servlet engine (it could be
331
* using ajp12 for some requests and ajp13/ajp14 for others). Or, a single web
332
* server instance could have multiple workers communicating with different
333
* servlet engines using the same protocol (it could be load balancing
334
* among many engines, using ajp13/ajp14 for all communication).
336
* There is also a load balancing worker (jk_lb_worker.c), which itself
337
* manages a group of workers.
339
* Web servers are configured to forward requests to a given worker. To
340
* handle those requests, the worker's get_endpoint method is called, and
341
* then the service() method of that endpoint is called.
343
* As with all the core jk classes, this is essentially an abstract base
344
* class which is implemented/extended by classes which are specific to a
345
* particular protocol (or request-handling system). By using an abstract
346
* base class in this manner, plugins can be written for different servers
347
* (e.g. IIS, Apache) without the plugins having to worry about which
348
* protocol they are talking.
350
* This particular OO-in-C system uses a 'worker_private' pointer to
351
* point to the protocol-specific data/functions. So in the subclasses, the
352
* methods do most of their work by getting their hands on the
353
* worker_private pointer and then using that to get at the functions for
356
* Try imagining this as a 'public abstract class', and the
357
* worker_private pointer as a sort of extra 'this' reference. Or
358
* imagine that you are seeing the internal vtables of your favorite OO
359
* language. Whatever works for you.
361
* See jk_ajp14_worker.c, jk_ajp13_worker.c and jk_ajp12_worker.c for examples.
367
* Public property to enable the number of retry attempts
372
* A 'this' pointer which is used by the subclasses of this class to
373
* point to data/functions which are specific to a given protocol
374
* (e.g. ajp12 or ajp13 or ajp14).
376
void *worker_private;
380
* For all of the below (except destroy), the first argument is
381
* essentially a 'this' pointer.
385
* Given a worker which is in the process of being created, and a list
386
* of configuration options (or 'properties'), check to see if it the
387
* options are. This will always be called before the init() method.
388
* The init/validate distinction is a bit hazy to me.
389
* See jk_ajp13_worker.c/jk_ajp14_worker.c and jk_worker.c->wc_create_worker()
391
int (JK_METHOD * validate) (jk_worker_t *w,
393
jk_worker_env_t *we, jk_logger_t *l);
396
* Update worker either from jk_status or reloading from workers.properties
398
int (JK_METHOD * update) (jk_worker_t *w,
400
jk_worker_env_t *we, jk_logger_t *l);
403
* Do whatever initialization needs to be done to start this worker up.
404
* Configuration options are passed in via the props parameter.
406
int (JK_METHOD * init) (jk_worker_t *w,
408
jk_worker_env_t *we, jk_logger_t *l);
412
* Obtain an endpoint to service a particular request. A pointer to
413
* the endpoint is stored in pend.
415
int (JK_METHOD * get_endpoint) (jk_worker_t *w,
416
jk_endpoint_t **pend, jk_logger_t *l);
419
* Shutdown this worker. The first argument is not a 'this' pointer,
420
* but rather a pointer to 'this', so that the object can be free'd (I
421
* think -- though that doesn't seem to be happening. Hmmm).
423
int (JK_METHOD * destroy) (jk_worker_t **w, jk_logger_t *l);
426
* Maintain this worker.
428
int (JK_METHOD * maintain) (jk_worker_t *w, jk_logger_t *l);
433
* Essentially, an abstract base class (or factory class) with a single
434
* method -- think of it as createWorker() or the Factory Method Design
435
* Pattern. There is a different worker_factory function for each of the
436
* different types of workers. The set of all these functions is created
437
* at startup from the list in jk_worker_list.h, and then the correct one
438
* is chosen in jk_worker.c->wc_create_worker(). See jk_worker.c and
439
* jk_ajp13_worker.c/jk_ajp14_worker.c for examples.
441
* This allows new workers to be written without modifing the plugin code
442
* for the various web servers (since the only link is through
445
typedef int (JK_METHOD * worker_factory) (jk_worker_t **w,
449
void jk_init_ws_service(jk_ws_service_t *s);
454
#endif /* __cplusplus */
456
#endif /* JK_SERVICE_H */
added
removed
jk/native/common/jk_service.h
