rubbos/app/tomcat-connectors-1.2.32-src/native/common/jk_service.h

   1 /*
   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
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  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.
  16  */
  17
  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  ***************************************************************************/
  27
  28 #ifndef JK_SERVICE_H
  29 #define JK_SERVICE_H
  30
  31 #include "jk_global.h"
  32 #include "jk_logger.h"
  33 #include "jk_pool.h"
  34 #include "jk_map.h"
  35 #include "jk_uri_worker_map.h"
  36 #include "jk_msg_buff.h"
  37
  38 #define JK_RETRIES 2
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #endif                          /* __cplusplus */
  44
  45 /*
  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....
  49  */
  50
  51 struct jk_worker_env
  52 {
  53
  54     /* The original configuration map */
  55     jk_map_t *init_data;
  56
  57     /* The URI to WORKER map, will be feeded by AJP14 autoconf feature */
  58     jk_uri_worker_map_t *uri_to_worker;
  59
  60     unsigned int num_of_workers;
  61     char **worker_list;
  62
  63     /* Web-Server we're running on (Apache/IIS/NES) */
  64     char *server_name;
  65
  66     /* Virtual server handled - "*" is all virtual */
  67     char *virtual;
  68
  69     /* Optional APR pool used for configuration */
  70     void *pool;
  71 };
  72 typedef struct jk_worker_env jk_worker_env_t;
  73
  74 struct jk_ws_service;
  75 struct jk_endpoint;
  76 struct jk_worker;
  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;
  80
  81 struct svc_extension
  82 {
  83     /* reply_timeout overwrite */
  84     int reply_timeout;
  85     /* activation state overwrites for load balancers */
  86     /* Dynamically allocated array with one entry per lb member. */
  87     int *activation;
  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. */
  92     int *fail_on_status;
  93     /* Use server error pages for responses >= 400. */
  94     int use_server_error_pages;
  95 };
  96 typedef struct svc_extension svc_extension_t;
  97
  98 /*
  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.
 105  *
 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
 111  * talking to.
 112  *
 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
 117  * their platform.
 118  *
 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
 122  * works for you.
 123  *
 124  * See apache1.3/mod_jk.c and iis/jk_isapi_plugin.c for examples.
 125  */
 126 struct jk_ws_service
 127 {
 128
 129     /*
 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).
 133      */
 134     void *ws_private;
 135
 136     /*
 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.
 140      *
 141      * Alive as long as the request is alive.
 142      */
 143     jk_pool_t *pool;
 144
 145     /*
 146      * CGI Environment needed by servlets
 147      */
 148     const char *method;
 149     const char *protocol;
 150     char *req_uri;
 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 */
 165
 166     /*
 167      * SSL information
 168      *
 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
 174      *
 175      * In some servers it is impossible to extract all this information, in this
 176      * case, we are passing NULL.
 177      */
 178     int is_ssl;
 179     char *ssl_cert;
 180     unsigned ssl_cert_len;
 181     char *ssl_cipher;
 182     char *ssl_session;
 183
 184     /*
 185      * SSL extra information for Servlet 2.3 API
 186      *
 187      * ssl_key_size - ssl key size in use
 188      */
 189     int ssl_key_size;
 190
 191     /*
 192      * Headers, names and values.
 193      */
 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     */
 197
 198
 199     /*
 200      * Request attributes.
 201      *
 202      * These attributes that were extracted from the web server and are
 203      * sent to Tomcat.
 204      *
 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.
 208      */
 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     */
 212
 213     /*
 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
 217      * affinity
 218      */
 219     const char *route;
 220
 221     /*
 222      * Activation state of the worker in the load balancer.
 223      * Will be forwarded as a request attribute.
 224      */
 225     const char *activation;
 226
 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,
 231        and it'll work.
 232      */
 233     const char *secret;
 234
 235     /*
 236      * Area to get POST data for fail-over recovery in POST
 237      */
 238     jk_msg_buf_t *reco_buf;
 239     int reco_status;
 240
 241     /*
 242      * If set call flush after each write
 243      */
 244     int flush_packets;
 245
 246     /*
 247      * If set call flush after AJP13_SEND_HEADERS.
 248      */
 249     int flush_header;
 250
 251     /*
 252      * service extensions
 253      */
 254     svc_extension_t extension;
 255
 256     /*
 257      * JK_TRUE if response headers have been sent back
 258      */
 259     int response_started;
 260
 261     /*
 262      * JK_TRUE if response should not be send to the client
 263      */
 264     int response_blocked;
 265
 266     /*
 267      * HTTP status sent from container.
 268      */
 269     int http_response_status;
 270
 271     /* Uri worker map. Added for virtual host support
 272      */
 273     jk_uri_worker_map_t *uw_map;
 274
 275     /*
 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.
 279      */
 280     /*
 281      * Send the response headers to the browser.
 282      */
 283     int (JK_METHOD * start_response) (jk_ws_service_t *s,
 284                                       int status,
 285                                       const char *reason,
 286                                       const char *const *header_names,
 287                                       const char *const *header_values,
 288                                       unsigned num_of_headers);
 289
 290     /*
 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
 293      * actually_read.
 294      */
 295     int (JK_METHOD * read) (jk_ws_service_t *s,
 296                             void *buffer,
 297                             unsigned len, unsigned *actually_read);
 298
 299     /*
 300      * Write a chunk of response data back to the browser.
 301      */
 302     int (JK_METHOD * write) (jk_ws_service_t *s,
 303                              const void *buffer, unsigned len);
 304
 305     /*
 306      * Flush a chunk of response data back to the browser.
 307      */
 308     void (JK_METHOD * flush) (jk_ws_service_t *s);
 309
 310     /*
 311      * Done with sending response back to the browser.
 312      */
 313     void (JK_METHOD * done) (jk_ws_service_t *s);
 314
 315     /*
 316      * If set do not reuse socket after each full response
 317      */
 318     int disable_reuse;
 319
 320     /*
 321      * Add more data to log facilities.
 322      */
 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);
 327
 328     /*
 329      * Iterate through all vhosts
 330      */
 331     void *(JK_METHOD * next_vhost) (void *d);
 332
 333     /*
 334      * String representation of a vhost
 335      */
 336     void (JK_METHOD * vhost_to_text) (void *d, char *buf, size_t len);
 337
 338     /*
 339      * Get uw_map associated with a vhost
 340      */
 341     jk_uri_worker_map_t *(JK_METHOD * vhost_to_uw_map) (void *d);
 342 };
 343
 344 /*
 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
 350  * every request).
 351  *
 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.
 354  *
 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.
 360  *
 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
 365  * their protocol.
 366  *
 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.
 371  *
 372  * See jk_ajp13_worker.c/jk_ajp14_worker.c and jk_ajp12_worker.c for examples.
 373  */
 374 struct jk_endpoint
 375 {
 376     jk_uint64_t rd;
 377     jk_uint64_t wr;
 378
 379     /*
 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.
 384      */
 385     int recoverable;
 386
 387     /*
 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).
 391      */
 392     void *endpoint_private;
 393
 394     /*
 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.
 399      */
 400     int (JK_METHOD * service) (jk_endpoint_t *e,
 401                                jk_ws_service_t *s,
 402                                jk_logger_t *l, int *is_error);
 403
 404     /*
 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.
 409      *
 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.
 413      */
 414     int (JK_METHOD * done) (jk_endpoint_t **p, jk_logger_t *l);
 415 };
 416
 417 /*
 418  * The worker 'class', which represents something to which the web server
 419  * can delegate requests.
 420  *
 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).
 428  *
 429  * There is also a load balancing worker (jk_lb_worker.c), which itself
 430  * manages a group of workers.
 431  *
 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.
 435  *
 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.
 442  *
 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
 447  * their protocol.
 448  *
 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.
 453  *
 454  * See jk_ajp14_worker.c, jk_ajp13_worker.c and jk_ajp12_worker.c for examples.
 455  */
 456 struct jk_worker
 457 {
 458
 459     jk_worker_env_t *we;
 460
 461     /*
 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).
 465      */
 466     void *worker_private;
 467
 468     int   type;
 469     /*
 470      * For all of the below (except destroy), the first argument is
 471      * essentially a 'this' pointer.
 472      */
 473
 474     /*
 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()
 480      */
 481     int (JK_METHOD * validate) (jk_worker_t *w,
 482                                 jk_map_t *props,
 483                                 jk_worker_env_t *we, jk_logger_t *l);
 484
 485     /*
 486      * Update worker either from jk_status or reloading from workers.properties
 487      */
 488     int (JK_METHOD * update) (jk_worker_t *w,
 489                               jk_map_t *props,
 490                               jk_worker_env_t *we, jk_logger_t *l);
 491
 492     /*
 493      * Do whatever initialization needs to be done to start this worker up.
 494      * Configuration options are passed in via the props parameter.
 495      */
 496     int (JK_METHOD * init) (jk_worker_t *w,
 497                             jk_map_t *props,
 498                             jk_worker_env_t *we, jk_logger_t *l);
 499
 500
 501     /*
 502      * Obtain an endpoint to service a particular request.  A pointer to
 503      * the endpoint is stored in pend.
 504      */
 505     int (JK_METHOD * get_endpoint) (jk_worker_t *w,
 506                                     jk_endpoint_t **pend, jk_logger_t *l);
 507
 508     /*
 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).
 512      */
 513     int (JK_METHOD * destroy) (jk_worker_t **w, jk_logger_t *l);
 514
 515     /*
 516      * Maintain this worker.
 517      */
 518     int (JK_METHOD * maintain) (jk_worker_t *w, time_t now, jk_logger_t *l);
 519
 520 };
 521
 522 /*
 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.
 530  *
 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
 533  * jk_worker_list.h).
 534  */
 535 typedef int (JK_METHOD * worker_factory) (jk_worker_t **w,
 536                                           const char *name,
 537                                           jk_logger_t *l);
 538
 539 void jk_init_ws_service(jk_ws_service_t *s);
 540
 541
 542 #ifdef __cplusplus
 543 }
 544 #endif                          /* __cplusplus */
 545
 546 #endif                          /* JK_SERVICE_H */