2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
18 /***************************************************************************
19 * Description: Definitions of the objects used during the service step. *
20 * These are the web server (ws) the worker and the connection*
21 * JVM connection point *
22 * Author: Gal Shachor <shachor@il.ibm.com> *
23 * Author: Dan Milstein <danmil@shore.net> *
24 * Author: Henri Gomez <hgomez@apache.org> *
25 * Version: $Revision: 1078846 $ *
26 ***************************************************************************/
31 #include "jk_global.h"
32 #include "jk_logger.h"
35 #include "jk_uri_worker_map.h"
36 #include "jk_msg_buff.h"
43 #endif /* __cplusplus */
46 * Env Information to be provided to worker at init time
47 * With AJP14 support we need to have access to many informations
48 * about web-server, uri to worker map....
54 /* The original configuration map */
57 /* The URI to WORKER map, will be feeded by AJP14 autoconf feature */
58 jk_uri_worker_map_t *uri_to_worker;
60 unsigned int num_of_workers;
63 /* Web-Server we're running on (Apache/IIS/NES) */
66 /* Virtual server handled - "*" is all virtual */
69 /* Optional APR pool used for configuration */
72 typedef struct jk_worker_env jk_worker_env_t;
77 typedef struct jk_ws_service jk_ws_service_t;
78 typedef struct jk_endpoint jk_endpoint_t;
79 typedef struct jk_worker jk_worker_t;
83 /* reply_timeout overwrite */
85 /* activation state overwrites for load balancers */
86 /* Dynamically allocated array with one entry per lb member. */
88 /* fail_on_status overwrites */
89 /* Number of elements in the array fail_on_status. */
90 int fail_on_status_size;
91 /* Dynamically allocated array with one entry per status. */
93 /* Use server error pages for responses >= 400. */
94 int use_server_error_pages;
96 typedef struct svc_extension svc_extension_t;
99 * The web server service 'class'. An instance of this class is created
100 * for each request which is forwarded from the web server to the servlet
101 * container. Contains the basic information about the request
102 * (e.g. protocol, req_uri, etc), and also contains a series of methods
103 * which provide access to core web server functionality (start_response,
104 * read, write). This class might be more accurately called ws_request.
106 * As with all the core jk classes, this is essentially an abstract base
107 * class which is implemented/extended by classes which are specific to a
108 * particular web server. By using an abstract base class in this manner,
109 * workers can be written for different protocols (e.g. ajp12, ajp13, ajp14)
110 * without the workers having to worry about which web server they are
113 * This particular OO-in-C system uses a 'ws_private' pointer to point to
114 * the platform-specific data. So in the subclasses, the methods do most
115 * of their work by getting their hands on the ws_private pointer and then
116 * using that to get at the correctly formatted data and functions for
119 * Try imagining this as a 'public abstract class', and the ws_private
120 * pointer as a sort of extra 'this' reference. Or imagine that you are
121 * seeing the internal vtables of your favorite OO language. Whatever
124 * See apache1.3/mod_jk.c and iis/jk_isapi_plugin.c for examples.
130 * A 'this' pointer which is used by the subclasses of this class to
131 * point to data which is specific to a given web server platform
132 * (e.g. Apache or IIS).
137 * Provides memory management. All data specific to this request is
138 * allocated within this pool, which can then be reclaimed at the end
139 * of the request handling cycle.
141 * Alive as long as the request is alive.
146 * CGI Environment needed by servlets
149 const char *protocol;
151 const char *remote_addr;
152 const char *remote_port;
153 const char *remote_host;
154 const char *remote_user;
155 const char *auth_type;
156 const char *query_string;
157 const char *server_name;
158 unsigned server_port;
159 char *server_software;
160 jk_uint64_t content_length; /* 64 bit integer that represents the content */
161 /* length should be 0 if unknown. */
162 unsigned is_chunked; /* 1 if content length is unknown (chunked rq) */
163 unsigned no_more_chunks; /* 1 if last chunk has been read */
164 jk_uint64_t content_read; /* number of bytes read */
169 * is_ssl - True if request is in ssl connection
170 * ssl_cert - If available, base64 ASN.1 encoded client certificates.
171 * ssl_cert_len - Length of ssl_cert, 0 if certificates are not available.
172 * ssl_cipher - The ssl cipher suite in use.
173 * ssl_session - The ssl session string
175 * In some servers it is impossible to extract all this information, in this
176 * case, we are passing NULL.
180 unsigned ssl_cert_len;
185 * SSL extra information for Servlet 2.3 API
187 * ssl_key_size - ssl key size in use
192 * Headers, names and values.
194 char **headers_names; /* Names of the request headers */
195 char **headers_values; /* Values of the request headers */
196 unsigned num_headers; /* Number of request headers */
200 * Request attributes.
202 * These attributes that were extracted from the web server and are
205 * The developer should be able to read them from the ServletRequest
206 * attributes. Tomcat is required to append org.apache.tomcat. to
207 * these attrinbute names.
209 char **attributes_names; /* Names of the request attributes */
210 char **attributes_values; /* Values of the request attributes */
211 unsigned num_attributes; /* Number of request attributes */
214 * The route is in use when the adapter load balance among
215 * several workers. It is the ID of a specific target in the load balance
216 * group. We are using this variable to implement target session
222 * Activation state of the worker in the load balancer.
223 * Will be forwarded as a request attribute.
225 const char *activation;
227 /* Temp solution for auth. For native1 it'll be sent on each request,
228 if an option is present. For native2 it'll be sent with the first
229 request. On java side, both cases will work. For tomcat3.2 or
230 a version that doesn't support secret - don't set the secret,
236 * Area to get POST data for fail-over recovery in POST
238 jk_msg_buf_t *reco_buf;
242 * If set call flush after each write
247 * If set call flush after AJP13_SEND_HEADERS.
254 svc_extension_t extension;
257 * JK_TRUE if response headers have been sent back
259 int response_started;
262 * JK_TRUE if response should not be send to the client
264 int response_blocked;
267 * HTTP status sent from container.
269 int http_response_status;
271 /* Uri worker map. Added for virtual host support
273 jk_uri_worker_map_t *uw_map;
276 * Callbacks into the web server. For each, the first argument is
277 * essentially a 'this' pointer. All return JK_TRUE on success
278 * and JK_FALSE on failure.
281 * Send the response headers to the browser.
283 int (JK_METHOD * start_response) (jk_ws_service_t *s,
286 const char *const *header_names,
287 const char *const *header_values,
288 unsigned num_of_headers);
291 * Read a chunk of the request body into a buffer. Attempt to read len
292 * bytes into the buffer. Write the number of bytes actually read into
295 int (JK_METHOD * read) (jk_ws_service_t *s,
297 unsigned len, unsigned *actually_read);
300 * Write a chunk of response data back to the browser.
302 int (JK_METHOD * write) (jk_ws_service_t *s,
303 const void *buffer, unsigned len);
306 * Flush a chunk of response data back to the browser.
308 void (JK_METHOD * flush) (jk_ws_service_t *s);
311 * Done with sending response back to the browser.
313 void (JK_METHOD * done) (jk_ws_service_t *s);
316 * If set do not reuse socket after each full response
321 * Add more data to log facilities.
323 void (JK_METHOD * add_log_items) (jk_ws_service_t *s,
324 const char *const *log_names,
325 const char *const *log_values,
326 unsigned num_of_items);
329 * Iterate through all vhosts
331 void *(JK_METHOD * next_vhost) (void *d);
334 * String representation of a vhost
336 void (JK_METHOD * vhost_to_text) (void *d, char *buf, size_t len);
339 * Get uw_map associated with a vhost
341 jk_uri_worker_map_t *(JK_METHOD * vhost_to_uw_map) (void *d);
345 * The endpoint 'class', which represents one end of a connection to the
346 * servlet engine. Basically, supports nothing other than forwarding the
347 * request to the servlet engine. Endpoints can be persistent (as with
348 * ajp13/ajp14, where a single connection is reused many times), or can last for a
349 * single request (as with ajp12, where a new connection is created for
352 * An endpoint for a given protocol is obtained by the web server plugin
353 * from a worker object for that protocol. See below for details.
355 * As with all the core jk classes, this is essentially an abstract base
356 * class which is implemented/extended by classes which are specific to a
357 * particular protocol. By using an abstract base class in this manner,
358 * plugins can be written for different servers (e.g. IIS, Apache) without
359 * the plugins having to worry about which protocol they are talking.
361 * This particular OO-in-C system uses a 'endpoint_private' pointer to
362 * point to the protocol-specific data/functions. So in the subclasses, the
363 * methods do most of their work by getting their hands on the
364 * endpoint_private pointer and then using that to get at the functions for
367 * Try imagining this as a 'public abstract class', and the
368 * endpoint_private pointer as a sort of extra 'this' reference. Or
369 * imagine that you are seeing the internal vtables of your favorite OO
370 * language. Whatever works for you.
372 * See jk_ajp13_worker.c/jk_ajp14_worker.c and jk_ajp12_worker.c for examples.
380 * Flag to pass back recoverability status from
381 * a load balancer member to the load balancer itself.
382 * Depending on the configuration and request status
383 * recovery is not allowed.
388 * A 'this' pointer which is used by the subclasses of this class to
389 * point to data/functions which are specific to a given protocol
390 * (e.g. ajp12 or ajp13 or ajp14).
392 void *endpoint_private;
395 * Forward a request to the servlet engine. The request is described
396 * by the jk_ws_service_t object.
397 * is_error is either 0 meaning recoverable or set to
398 * the HTTP error code.
400 int (JK_METHOD * service) (jk_endpoint_t *e,
402 jk_logger_t *l, int *is_error);
405 * Called when this particular endpoint has finished processing a
406 * request. For some protocols (e.g. ajp12), this frees the memory
407 * associated with the endpoint. For others (e.g. ajp13/ajp14), this can
408 * return the endpoint to a cache of already opened endpoints.
410 * Note that the first argument is *not* a 'this' pointer, but is
411 * rather a pointer to a 'this' pointer. This is necessary, because
412 * we may need to free this object.
414 int (JK_METHOD * done) (jk_endpoint_t **p, jk_logger_t *l);
418 * The worker 'class', which represents something to which the web server
419 * can delegate requests.
421 * This can mean communicating with a particular servlet engine instance,
422 * using a particular protocol. A single web server instance may have
423 * multiple workers communicating with a single servlet engine (it could be
424 * using ajp12 for some requests and ajp13/ajp14 for others). Or, a single web
425 * server instance could have multiple workers communicating with different
426 * servlet engines using the same protocol (it could be load balancing
427 * among many engines, using ajp13/ajp14 for all communication).
429 * There is also a load balancing worker (jk_lb_worker.c), which itself
430 * manages a group of workers.
432 * Web servers are configured to forward requests to a given worker. To
433 * handle those requests, the worker's get_endpoint method is called, and
434 * then the service() method of that endpoint is called.
436 * As with all the core jk classes, this is essentially an abstract base
437 * class which is implemented/extended by classes which are specific to a
438 * particular protocol (or request-handling system). By using an abstract
439 * base class in this manner, plugins can be written for different servers
440 * (e.g. IIS, Apache) without the plugins having to worry about which
441 * protocol they are talking.
443 * This particular OO-in-C system uses a 'worker_private' pointer to
444 * point to the protocol-specific data/functions. So in the subclasses, the
445 * methods do most of their work by getting their hands on the
446 * worker_private pointer and then using that to get at the functions for
449 * Try imagining this as a 'public abstract class', and the
450 * worker_private pointer as a sort of extra 'this' reference. Or
451 * imagine that you are seeing the internal vtables of your favorite OO
452 * language. Whatever works for you.
454 * See jk_ajp14_worker.c, jk_ajp13_worker.c and jk_ajp12_worker.c for examples.
462 * A 'this' pointer which is used by the subclasses of this class to
463 * point to data/functions which are specific to a given protocol
464 * (e.g. ajp12 or ajp13 or ajp14).
466 void *worker_private;
470 * For all of the below (except destroy), the first argument is
471 * essentially a 'this' pointer.
475 * Given a worker which is in the process of being created, and a list
476 * of configuration options (or 'properties'), check to see if it the
477 * options are. This will always be called before the init() method.
478 * The init/validate distinction is a bit hazy to me.
479 * See jk_ajp13_worker.c/jk_ajp14_worker.c and jk_worker.c->wc_create_worker()
481 int (JK_METHOD * validate) (jk_worker_t *w,
483 jk_worker_env_t *we, jk_logger_t *l);
486 * Update worker either from jk_status or reloading from workers.properties
488 int (JK_METHOD * update) (jk_worker_t *w,
490 jk_worker_env_t *we, jk_logger_t *l);
493 * Do whatever initialization needs to be done to start this worker up.
494 * Configuration options are passed in via the props parameter.
496 int (JK_METHOD * init) (jk_worker_t *w,
498 jk_worker_env_t *we, jk_logger_t *l);
502 * Obtain an endpoint to service a particular request. A pointer to
503 * the endpoint is stored in pend.
505 int (JK_METHOD * get_endpoint) (jk_worker_t *w,
506 jk_endpoint_t **pend, jk_logger_t *l);
509 * Shutdown this worker. The first argument is not a 'this' pointer,
510 * but rather a pointer to 'this', so that the object can be free'd (I
511 * think -- though that doesn't seem to be happening. Hmmm).
513 int (JK_METHOD * destroy) (jk_worker_t **w, jk_logger_t *l);
516 * Maintain this worker.
518 int (JK_METHOD * maintain) (jk_worker_t *w, time_t now, jk_logger_t *l);
523 * Essentially, an abstract base class (or factory class) with a single
524 * method -- think of it as createWorker() or the Factory Method Design
525 * Pattern. There is a different worker_factory function for each of the
526 * different types of workers. The set of all these functions is created
527 * at startup from the list in jk_worker_list.h, and then the correct one
528 * is chosen in jk_worker.c->wc_create_worker(). See jk_worker.c and
529 * jk_ajp13_worker.c/jk_ajp14_worker.c for examples.
531 * This allows new workers to be written without modifing the plugin code
532 * for the various web servers (since the only link is through
535 typedef int (JK_METHOD * worker_factory) (jk_worker_t **w,
539 void jk_init_ws_service(jk_ws_service_t *s);
544 #endif /* __cplusplus */
546 #endif /* JK_SERVICE_H */