Architecture¶

This document describes the internal architecture of Apache Axis2/C.

High-Level Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                    Client Applications                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Transport Layer                           │
│  ┌─────────────────────┐    ┌─────────────────────┐        │
│  │  HTTP/2 Transport   │    │  HTTP/1.1 Transport │        │
│  │  (nghttp2 + TLS)    │    │  (Legacy SOAP)      │        │
│  └─────────────────────┘    └─────────────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Axis2/C Engine                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 Handler Chain                        │   │
│  │  In Flow  → [Handler] → [Handler] → [Dispatch]      │   │
│  │  Out Flow ← [Handler] ← [Handler] ←                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Message Receivers                       │   │
│  │  ┌───────────────┐  ┌───────────────┐              │   │
│  │  │ JSON Receiver │  │ SOAP Receiver │              │   │
│  │  └───────────────┘  └───────────────┘              │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Service Layer                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Service A  │  │  Service B  │  │  Service C  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

Core Components¶

Engine (`axis2_engine`)¶

The engine orchestrates request processing:

Receives requests from transport
Executes handler chains
Dispatches to appropriate service
Processes responses through out-flow handlers

Message Context (`axis2_msg_ctx`)¶

Carries all information about a request/response:

typedef struct axis2_msg_ctx {
    /* Transport info */
    axis2_transport_in_desc_t *transport_in;
    axis2_transport_out_desc_t *transport_out;

    /* Protocol info */
    axis2_bool_t is_http2;
    axis2_char_t *content_type;

    /* Security context */
    axis2_char_t *client_cert_dn;

    /* Service/operation */
    axis2_svc_t *svc;
    axis2_op_t *op;

    /* Request/response bodies */
    axiom_soap_envelope_t *soap_envelope;  /* SOAP */
    axiom_node_t *json_node;               /* JSON */
} axis2_msg_ctx_t;

Handler Chain¶

Handlers process messages in phases:

Inflow Phases:
  Transport → PreDispatch → Dispatch → PostDispatch

Outflow Phases:
  PreSend → MessageOut → Transport

Service Skeleton¶

Services implement the skeleton interface:

typedef struct axis2_svc_skeleton_ops {
    /* Main request handler */
    axiom_node_t* (AXIS2_CALL *invoke)(
        axis2_svc_skeleton_t *svc_skeleton,
        const axutil_env_t *env,
        axiom_node_t *node,
        axis2_msg_ctx_t *msg_ctx);

    /* Error handler */
    axiom_node_t* (AXIS2_CALL *on_fault)(
        axis2_svc_skeleton_t *svc_skeleton,
        const axutil_env_t *env,
        axiom_node_t *node);

    /* Lifecycle */
    int (AXIS2_CALL *init)(axis2_svc_skeleton_t *svc_skeleton,
                           const axutil_env_t *env);
    int (AXIS2_CALL *free)(axis2_svc_skeleton_t *svc_skeleton,
                           const axutil_env_t *env);
} axis2_svc_skeleton_ops_t;

Module System¶

Modules extend Axis2/C functionality:

modules/
├── addressing/
│   ├── libmod_addr.so
│   └── module.xml
└── rampart/
    ├── libmod_rampart.so
    └── module.xml

Modules can:

Add handlers to the processing chain
Provide utility functions
Implement WS-* specifications (legacy)

Memory Management¶

Axis2/C uses an environment-based allocator:

/* Create environment with custom allocator */
axutil_env_t *env = axutil_env_create_all("app.log", AXIS2_LOG_LEVEL_INFO);

/* All allocations through environment */
char *str = AXIS2_MALLOC(env->allocator, 256);

/* Free through environment */
AXIS2_FREE(env->allocator, str);

/* Environment cleanup frees all tracked memory */
axutil_env_free(env);

Thread Safety¶

Axis2/C supports multi-threaded deployment:

Message contexts are per-request (not shared)
Service instances can be shared (thread-safe skeleton required)
Configuration is read-only after startup