Petals Link
Petals ESB

TestLink logo

Petals ESB - SE Assured Service Execution (ASE)

Requirements Specification Document

Project: Petals ESB

Author: cdeneux

Printed by TestLink on 06/15/2011

Table Of Contents


1. SE-ASE : SE Assured Service Execution (ASE)

SE-ASE-ABSTRACT : Abstract

SE-ASE-DEFINITIONS : Definitions - Terminology

SE-ASE-CONCEPTS : Main concepts

SE-ASE-SYSTEM : System requirements

SE-ASE-RELEASE-PLAN : Release Plan

1.1. SE-ASE-PROCESSING : Processing

SE-ASE-PROC-000 : Deploying a service unit

SE-ASE-PROC-005 : Starting a service unit

SE-ASE-PROC-006 : Starting the posting process

SE-ASE-PROC-007 : Starting the sending process

SE-ASE-PROC-020 : Processing a incoming request (Posting Process)

SE-ASE-PROC-025 : Processing a persisted request (Sending Process)

SE-ASE-PROC-026 : Retry policy on timeout or error (In a next version)

SE-ASE-PROC-027 : Time-to-Live (In a next version)

SE-ASE-PROC-050 : Stopping a service unit

SE-ASE-PROC-051 : Stopping the posting process

SE-ASE-PROC-052 : Stopping the sending process

SE-ASE-PROC-055 : Undeploying a service unit

SE-ASE-PROC-100 : Persistence system

1.2. SE-ASE-CFG : Component configuration

SE-ASE-CFG-000 : Configuring the component

SE-ASE-CFG-005 : Persistence system parameters

SE-ASE-CFG-010 : Runtime parameters

1.3. SE-ASE-ADMINISTRATION : Administration

SE-ASE-ADM-001 : JMX API

SE-ASE-ADM-005 : Identifying a persistence area

SE-ASE-ADM-010 : Purging a persistence area (In a next version)

SE-ASE-ADM-015 : Recycling a persistence area (In a next version)

SE-ASE-ADM-025 : Starting the posting process

SE-ASE-ADM-020 : Stopping the posting process

SE-ASE-ADM-035 : Starting the sending process

SE-ASE-ADM-030 : Stopping the sending process

1.4. SE-ASE-MONITORING : Monitoring

SE-ASE-MON-000 : JMX API

SE-ASE-MON-005 : Monitoring the persistence areas

SE-ASE-MON-010 : Monitoring the connection to the persistence system (In a next version)

SE-ASE-000 : Installing the component

SE-ASE-010 : Starting the component

SE-ASE-020 : Stopping the component

SE-ASE-ERRORS : Error messages

SE-ASE-INFOS : Information messages

SE-ASE-WARNS : Warning messages

Test Project Scope

Petals ESB is the project associated to:


Requirement Specification Report


1. Requirements Spec.: SE-ASE : SE Assured Service Execution (ASE)
Scope



Requirement: SE-ASE-ABSTRACT : Abstract
Scope


The main goals of the SE ASE (Assured Service Execution) is to assure to a client (service consumer) the execution of a target one-way service (service provider):

  • the incoming request is persisted before to be forwarded to the target service,
  • if the target service is not available when forwarding the request, the request remains persisted until the target service becomes again available,
  • if a persisted request has an expired TTL, it is enqueued for an administrative purpose,
  • if a crash occurs during the target service processing, the request will be send again when the infrastructure will be up,
  • if a fault (business error) is returned by the target service, it is enqueued for an administrative purpose,
  • if an error (technical error) or a timeout is returned by the target service, a retry policy is started,
  • the component can be instantiated several time to be integrated into a Petals topology.

Note: Robust one-way invocation is needed to do cascading invocations.


Requirement: SE-ASE-DEFINITIONS : Definitions - Terminology
Scope
  • ASE service provider, is the service provider that assures the execution of the target service provider,
  • target service provider, is the service provider for which the execution is assured by the ASE service provider,
  • persistence area: incoming requests are stored into a queue of the persistence area waiting the end of the request processing. A persistence area is composed of several queues,
  • posting process (PP): persist requests coming from an ASE service consumer,
  • sending process (SP): get request from persistence system to forward it to the target service provider,
  • fault: business error,
  • error: technical error.

Requirement: SE-ASE-CONCEPTS : Main concepts
Scope

For an existing service SVC-A (target service provider), this component will create a new service provider SVC-A' (ASE service provider) acting as a consumer of SVC-A. Both services, SVC-A and SVC-A', are differentiated by their service names (and endpoint names), they have the same interface name.

The processing of an incoming request is composed of two processes: the posting process and the sending process.

The posting process persists all incoming request received by SVC-A' into its dedicated persistence area.

The sending process listens requests available into the persistence area are listened. When a request is available, SVC-A is invoked:

  • the request will be removed from the persistence area when the acknowledgement/reply or fault is received,
  • if a crash occurs during execution of SVC-A, an error is returned or a timeout occurs, the request is resend automatically according to a retry policy. When the retry policy ends successfully, the request is removed from the persistence area, otherwise, the request is kept in a dedicated queue.

The mapping between SVC-A and SVC-A' is provided through the JBI descriptor of service-units deployed on the component. SVC-A and SVC-A' are declared respectively through the nodes 'consumes' and 'provides'.

By configuration, the both parts of the processing can be enabled independently.

Persistence areas are created when deploying the service-unit. When undeploying the service unit, the persistence areas are not destroyed. Several queues into one persistence area are used to manage request acknowledged with error or fault, expired request (TTL) or not-acknowledge request (timeout).

JMS is used as persistence areas. Each persistence area is mapped on several JMS queues. To be able to instantiate the component several times, it is connected to an external JMS server. If needed, the customer is responsible of the choice and the high availability of the JMS server.


Requirement: SE-ASE-SYSTEM : System requirements
Scope

This component is runing with Petals ESB 3.1.x running on:

  • JVM: Sun/Oracle JDK 1.6.0_24,
  • OS: Ubuntu Server,
  • architecture: 64bits

This component is not included into a Petals edition, so it will be subjected to a specific support contract.

The component user is responsible for:

  • choosing and configuring correctly the persistence area system, including HA
  • monitoring the persistence area system.

Requirement: SE-ASE-RELEASE-PLAN : Release Plan
Scope

First version 0.9.0:

  • the component will support only one JMS provider: ActiveMQ
  • Time-to-Live is not included,
  • retry policy is not included: the retry policy is delegated to ActiveMQ, see ActiveMQ documentation (http://activemq.apache.org/redelivery-policy.html), the component will only rollback the JMS message if an error or a timeout occurs invoking the target service,
  • administrative actions are uncompleted: queues management is not included.
  • monitoring is not included.

Note: Functions that are not included in this first version are highlighted in green.


1.1. Requirements Spec.: SE-ASE-PROCESSING : Processing
Scope

 

 


Requirement: SE-ASE-PROC-000 : Deploying a service unit
Scope

An ASE service provider is created from an existing target service provider deploying a service unit on the component. The ASE service is identified by the section 'provides'. The target service is identified by the section 'consumes'.

A new endpoint associated to the ASE service is created and activated on service-unit deployment:

  • new ASE service endpoint identification characteristics are defined in the service-unit JBI descriptor by the node 'jbi:provides',
  • characteristics of the target service are defined in the service-unit JBI descriptor by the node 'jbi:consumes'.

The queues of persistence area are created when deploying the service unit, according to the following rules:

  • if a queue does not already exist, it is created,
  • the queues to created are listed in the table below,
  • a queue is created to guarantee the persistence of messages,
  • the queue name can be set using an optional parameter (see the column 'parameter name'). A default queue name defined as the local part of the ASE service name suffix by the value of the column 'suffix of the default name',
  • the queue name parameter is located only once into the section 'jbi:provides' or 'jbi:consumes' of the JBI service unit descriptor.
queue content parameter name suffix of the default name
#1 incoming requests to process persistence-area-name -
#2 incoming requests expired persistence-area-name-expired _expired
#3 incoming requests processed with timeout persistence-area-name-timedout _error
#4 incoming requests processed with error persistence-area-name-error _error
#5 incoming requests processed with fault persistence-area-name-fault _error

When the persisted area queue #1 is created, a persisted request listener is created (not started). The persisted request listener reads a request from the persisted area and processes it.

Note 1: With a persistence area name defined as the local part of the ASE service, in a HA infrastructure where such a SU is deployed on two Petals node, the request persisted on a Petals node can be read by the component running on the other Petals node. So, a burst of incoming requests on a Petals node can be absorbed with several Petals nodes.

Note 2: Persistence areas are created concurrently. A same persistence area, used by two instances of the component on different Petals node, can be created concurrently from each node.

Ajouter parametre de worker du listener

Error management

If the JBI descriptor contains 2 sections 'provide':

  1. a message associated to the warning code 'SE-ASE-W0001' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the first section found is taken into account to create the new endpoint.

If the JBI descriptor contains 2 sections 'consume':

  1. a message associated to the warning code 'SE-ASE-W0002' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the first section found is taken into account to create the new endpoint.

If the interface names of both section 'consume' and 'provide' are different:

  1. a message associated to the warning code 'SE-ASE-W0003' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the interface name of the section 'consume' is used to declare the new endpoint.

If a queue name parameter is defined twice with the same value in both sections 'consumes' and 'provides' of the JBI service unit descriptor:

  1. a message associated to the warning code 'SE-ASE-W0012' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the queue name used is the value of the parameter.

If a queue name parameter is defined twice with different values in both sections 'consumes' and 'provides' of the JBI service unit descriptor:

  1. a message associated to the error code 'SE-ASE-E0022' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the deployment is aborted.

If an error occurs during the creation of the persistence area:

  1. a message associated to the error code 'SE-ASE-E0001' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the deployment is aborted.

If an error occurs during the creation of the persisted request listener:

  1. a message associated to the warning code 'SE-ASE-W0004' is logged with a WARNING level,
  2. no stack trace is logged.
  3. no persisted request will be processed.
  4. a human action will be needed to fix the problem before to overload the persistence area with too many requests.

If an error occurs when removing a request from the persisted are:

  1. a message associated to the error code 'SE-ASE-E0007' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the deployment is aborted.

 


Requirement: SE-ASE-PROC-005 : Starting a service unit
Scope

According to the value of the optional boolean parameter 'mustBeAutomaticallyStarted' of the service unit section 'provides', the posting process is started. The default value of 'mustBeAutomaticallyStarted' is 'true'. If 'mustBeAutomaticallyStarted' is true, the incoming messages listener is started. If false, it is not.

If correctly created, the sending process is started when the service unit is started according to the optional boolean parameter 'mustBeAutomaticallyStarted' of the service unit section 'consumes'. The default value of 'mustBeAutomaticallyStarted' is 'true'. If 'mustBeAutomaticallyStarted' is true, the persisted request listener is started. If false, it is not.

The value of the parameter 'mustBeAutomaticallyStarted' is logged with a CONFIG level.

Note 1: Using the parameters 'mustBeAutomaticallyStarted' of both service unit sections, it is possible:

  • to have more component instances processing persisted requests than saving requests. Interesting use-case in a HA platform,
  • to use the persistence area as message transporter if the persistence system is distributable

Note 2: To be more agile, use the placeholders and the component property file to set the value of 'mustBeAutomaticallyStarted'. So we have only deliverable to configure according to our needs.

Error management

If an error occurs during the start of the posting process or during the start of the sending process, the start of the service unit continues.

If the parameter 'mustBeAutomaticallyStarted' is not a boolean value:

  1. a message associated to the warning code 'SE-ASE-W0017' is logged with an WARNING level,
  2. no stack trace is logged.
  3. the start continues.

 

Relationsrelated to:
     SE-ASE-PROC-006 : Starting the posting process
     Status: Valid
related to:
     SE-ASE-PROC-007 : Starting the sending process
     Status: Valid

Requirement: SE-ASE-PROC-006 : Starting the posting process
Scope

If not already started, the posting process is started to persist incoming requests.

When the posting process is correctly started, a message associated to the information code 'SE-ASE-I0001' is logged with an INFO level.

Error management

If an error occurs during the start of the posting process:

  1. a message associated to the error code 'SE-ASE-E0019' is logged with a ERROR level,
  2. no stack trace is logged,
  3. the start of the incoming request listener is aborted.

 

Relationsrelated to:
     SE-ASE-PROC-005 : Starting a service unit
     Status: Valid
related to:
     SE-ASE-ADM-025 : Starting the posting process
     Status: Valid

Requirement: SE-ASE-PROC-007 : Starting the sending process
Scope

If correctly created and not already started, the sending process is started to process persisted requests.

When the sending process is correctly started, a message associated to the information code 'SE-ASE-I0002' is logged with an INFO level.

Error management

If an error occurs during the start of the sending process:

  1. a message associated to the warning code 'SE-ASE-W0023' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the start of the persisted request listener is aborted and no persisted request will be processed.

        Note: if the posting process was correctly started, a human action will be needed to fix the problem before to overload the persistence area with too many requests.

Relationsrelated to:
     SE-ASE-PROC-005 : Starting a service unit
     Status: Valid
related to:
     SE-ASE-ADM-035 : Starting the sending process
     Status: Valid

Requirement: SE-ASE-PROC-020 : Processing a incoming request (Posting Process)
Scope

Only one-way requests are accepted. A one-way request is mapped on following JBI message exchange pattern: InOnly and RobustInOnly.

When a one-way request is received, it is saved exchange into the persistence area of the associated ASE service provider. When the request is saved, an acknowledgment is sent to the service consumer.

A request message is saved in its entirety, as message exchange, in particular with its following information:

  • payload 'IN',
  • properties,
  • attachments.

and following additional information, set as property in the message exchange:

  • incoming timestamp: the timestamp of the request receipt. It is used to a Time-To-Live on the request. The incoming timestamp is hold by a property of the normalized message 'IN': "org.ow2.petals.ase.ttl.incoming-timestamp".

Note: The component manages a TTL itself because we can't trust the persistence system. For example, JMS specifications 1.1 mentions a JMS expiration (see §3.4.9) but does not guarantee that message will not be delivered, and does not mention a queue to place expired message. So, we can't re-post expired messages.

Error management

If the received request is not a one-way request:

  1. a message associated to the error code 'SE-ASE-E0010' is logged with an ERROR level,
  2. no stack trace is logged.
  3. an error/fault is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0010: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs saving the request in the persistence area:

  1. a message associated to the error code 'SE-ASE-E0011' is logged with an ERROR level,
  2. no stack trace is logged.
  3. an error/fault is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0011: <msg-body>" where <msg-body> is the message logged in 1.

 


Requirement: SE-ASE-PROC-025 : Processing a persisted request (Sending Process)
Scope

A request read from the persistence area is forwarded to the target service provider. The target service endpoint is elected from interface-name and service-name of the target service.

The request forward is done with a timeout defined by the parameter 'cdk:timeout' of the service unit section 'jbi:consumes'. If time out or error occurs, a retry policy is applied according to the idempotency of the target service.

On receipt of acknowledgement or fault from the target service provider, the read request is acknowledged to be removed from the persistence area. See below the error management if an error is returned or a timeout occurs.

How to manage crash vs idempotency ? Do we kept outgoing request ?

Error management

If an error is returned by the target service or the target service invocation timed out, a retry policy is applied.

If a fault is returned by the target service:

  1. the read request, as message exchange (so including the initial request and the fault), is moved to the persistence area of requests processed with fault,
  2. the read request is acknowledged to be remove from the persistence area.
  3. no error is logged.
  4. no stack trace is logged.

 

Relationsrelated to:
     SE-ASE-CFG-010 : Runtime parameters
     Status: Valid
related to:
     SE-ASE-PROC-026 : Retry policy on timeout or error (In a next version)
     Status: Valid
related to:
     SE-ASE-PROC-027 : Time-to-Live (In a next version)
     Status: Valid

Requirement: SE-ASE-PROC-026 : Retry policy on timeout or error (In a next version)
Scope

A retry policy is applied on target service invocation timed out or processed with error. To prevent problem of non-idempotent service when retrying the invocation, the retry policy is applied only if the target service is declared as idempotent.

A target service is declared as idempotent through the boolean parameter 'is-idempotent' of the service unit section 'jbi:consumes'. Default value 'false'.

The retry policy is defined with following optional parameters defined at the service unit level in the section 'jbi:consumes':

  • 'retry-policy-number': number of retry before to consider the invocation in error. Does not include the first invokation. Deafult value '3'.
  • 'retry-policy-base-interval': The first duration, in seconds. The duration between two invocations of the target service provider is defined as the multiplication of the last duration with 'retry-policy-factor'. Default value '10'.
  • 'retry-policy-factor': integer number to multiply by last duration. Default value '3'.

On each timeout detected, including the first one and last one:

  1. a message associated to the warning code 'SE-ASE-W0024' is logged with a WARNING level,
  2. no stack trace is logged.

On each error detected, including the first one and excluding the last one:

  1. a message associated to the warning code 'SE-ASE-W0022' is logged with a WARNING level,
  2. no stack trace is logged.

Note: To not fill it, the requests MUST not be kept in memory. How to do this ? Using a JMS retry policy ? Using a JMS message selector ?

Error management:

 If the last target service invokation timed out:

  1. the read request, as message exchange, is moved to the persistence area of timed-out requests.
  2. the read request is acknowledged to be remove from the persistence area.
  3. a message associated to the error code 'SE-ASE-E0017' is logged with a ERROR level,
  4. no stack trace is logged.

 If the last target service invocation is processed with error:

  1. the read request, as message exchange (so including the initial request and the error) is moved to the persistence area queue of requests processed with error.
  2. the read request is acknowledged to be remove from the persistence area queue of incoming request.
  3. a message associated to the error code 'SE-ASE-E0020' is logged with a ERROR level,
  4. no stack trace is logged.
If the duration of the whole retry process exceeds the TTL:
  1. a message associated to the warning code 'SE-ASE-W0016' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the TTL is increased to a value compliant with the retry policy.

If the value of the parameter 'is-idempotent' is not a boolean value:

  1. a message associated to the warning code 'SE-ASE-W0013' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the target service idempotency is defined according to the default value of parameter 'is-idempotent'.

 

Relationsrelated to:
     SE-ASE-PROC-025 : Processing a persisted request (Sending Process)
     Status: Valid

Requirement: SE-ASE-PROC-027 : Time-to-Live (In a next version)
Scope

A request read from the persistence area is forwarded to the target service if its Time-To-Live is not expired.

The TTL is controlled through the optional parameter 'time-to-live' of the service unit section 'jbi:consumes'. This parameter inherits from the same parameter defined at the component level.

The TTL is defined as expired when the instant resulting from the addition of the value of the parameter 'time-to-live' and the timestamp associated to the read request is exceeded.

Error management

If the Time-To-Live of the request is expired:

  1. the read request is moved to the persistence area queue of expired requests.
  2. the read request is acknowledged to be remove from the persistence area queue.
  3. a message associated to the warning code 'SE-ASE-W0011' is logged with a WARNING level,
  4. no stack trace is logged.

If the value of the parameter 'time-to-live' is not an integer number value:

  1. a message associated to the warning code 'SE-ASE-W0014' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the TTL is defined according to the value of this parameter at component level.
Relationsrelated to:
     SE-ASE-PROC-025 : Processing a persisted request (Sending Process)
     Status: Valid

Requirement: SE-ASE-PROC-050 : Stopping a service unit
Scope

When stopping a service unit:

  • the posting process is stopped, no requests will be persisted,
  • the sending process is stopped,
  • we wait the end of the pending processing of the persisted requests sent to the target service
  • we wait the end of the pending processing of the incoming requests saved into the persistence area

A timeout is used to prevent an infinite wait of the end of the processing of the pending persisted requests sent to the target service. The timeout is defined at the service unit level through the optional parameter 'stop-timeout' of the section 'jbi:provides'. This parameter inherits from the same parameter defined at the component level.

Error management

If an error occurs during the stop of the posting process or during the stop of the sending process, the stop of the service unit continues.

Relationsrelated to:
     SE-ASE-CFG-010 : Runtime parameters
     Status: Valid
related to:
     SE-ASE-020 : Stopping the component
     Status: Valid

Requirement: SE-ASE-PROC-051 : Stopping the posting process
Scope

If started, the posting process is stopped, no more incoming request is persisted.

When the posting process is correctly stopped, a message associated to the information code 'SE-ASE-I0003' is logged with a INFO level.

The pending processing of incoming request will end correctly. The stop processing does not wait their end.

Error management

If an error occurs during the stop of the posting process:

  1. a message associated to the warning code 'SE-ASE-W0009' is logged with a WARNING level,
  2. no stack trace is logged.
  3. incoming request may be processed.

 

Relationsrelated to:
     SE-ASE-ADM-020 : Stopping the posting process
     Status: Valid

Requirement: SE-ASE-PROC-052 : Stopping the sending process
Scope

If started, the sending process is stopped, and no more persisted request will be processed.

When the sending process is correctly stopped, a message associated to the information code 'SE-ASE-I0004' is logged with an INFO level.

The pending processing of persisted request will end correctly. The stop processing does not wait their end.

Error management

If an error occurs during the stop of the sending process:

  1. a message associated to the warning code 'SE-ASE-W0010' is logged with a WARNING level,
  2. no stack trace is logged.
  3. persisted request may be sent to the target service,
Relationsrelated to:
     SE-ASE-ADM-030 : Stopping the sending process
     Status: Valid

Requirement: SE-ASE-PROC-055 : Undeploying a service unit
Scope

To prevent loose of requests because of an involuntary undeployment, the persistence areas associated to the service-unit are not destroyed. The customer is responsible to destroy persistence areas directly through the persistence area system.


Requirement: SE-ASE-PROC-100 : Persistence system
Scope

The persistence area queues are mapped on JMS queues using the point-to-point communication model.

JMS queues are managed by an external JMS server. The customer is responsible of the JMS server and its correct configuration.

The JMS client driver is provided as a shared library.


1.2. Requirements Spec.: SE-ASE-CFG : Component configuration
Scope

Requirement: SE-ASE-CFG-000 : Configuring the component
Scope

All configuration parameters are available at following layers:

  • component JBI descriptor: the namespace of the parameters is defined as 'http://petals.ow2.org/components/ase/version-XXX' where XXX is the major digits of the component version,
  • JMX API,
  • Ant task.

 

Relationsblocks:
     SE-ASE-CFG-005 : Persistence system parameters
     Status: Valid

Requirement: SE-ASE-CFG-005 : Persistence system parameters
Scope

The following parameters define the connection to the JMS server:

  • the initial context factory class name to access the JNDI where the JMS connection factory can be found. This parameter is mandatory and has no default value,
  • the JNDI provider URL where the JMS connection factory can be found. This parameter is mandatory and has no default value,
  • the name of the JMS connection factory in the naming directory. This parameter is mandatory and has no default value.

They can not be hot-updated.

Component descriptor aspects

Parameters of the connection to the JMS server are defined in the component JBI descriptor as:

  • ase:java-naming-factory-initial: the initial context factory class name,
  • ase:java-naming-provider-url: the JNDI provider URL,
  • ase:jms-connection-factory-jndiname: the name of the JMS connection factory.

where 'ase' is the parameter namespace of the component.

JMX apects

Parameters of the connection to the JMS server are customizable through JMX attributes of the installer configuration MBean of the component:

  • javaNamingFactoryInitial: the initial context factory class name,
  • javaNamingProviderUrl: the JNDI provider URL,
  • jmsConnectionFactoryJndiname: the name of the JMS connection factory.

Ant tasks aspects

The properties used by the component installation Ant task to customize the connection to the JMS servers are the same as the JMX attributes defined previously.

Relationsdepends on:
     SE-ASE-CFG-000 : Configuring the component
     Status: Valid
depends on:
     COMP-COMMON-CFG-000 : Configuration of service unit parameter
     Status: Valid

Requirement: SE-ASE-CFG-010 : Runtime parameters
Scope

The runtime can be customized through the following parameters:

  • a stop timeout: to wait the end of processing of persisted requests sent to the target service before to force the stop of a service unit. The value of this parameter is the default value of the same parameter defined at the service unit level. Defalt value is 60 seconds.
  • a Time-To-Live: to not process old messages saved in persistence area. An infinite TTL is defined by the value '0'. The value is expressed in seconds. The default value is '0'.

They can be hot-updated.

Component descriptor aspects

Parameters of the runtime are defined in the component JBI descriptor as:

  • ase:stop-timeout: the stop timeout,
  • ase:time-to-live: the TTL.

where 'ase' is the parameter namespace of the component (see SE-ASE-CFG).

JMX apects

Parameters of the runtime are customizable through JMX attributes of the installer configuration MBean or runtime configuration MBean of the component:

  • stopTimeout: the stop timeout,
  • timeToLive: the TTL.

Ant tasks aspects

The properties used by the component installation Ant task to customize the runtime are the same as the JMX attributes defined previously.

Relationsrelated to:
     SE-ASE-PROC-050 : Stopping a service unit
     Status: Valid
related to:
     SE-ASE-PROC-025 : Processing a persisted request (Sending Process)
     Status: Valid

1.3. Requirements Spec.: SE-ASE-ADMINISTRATION : Administration
Scope

Requirement: SE-ASE-ADM-001 : JMX API
Scope

Administration actions are available through JMX.

The property 'name' of the MBean object name is 'Administration_<component-id>', where <component-id> is the unique component identifier.

A JMX MBean is created when the component starts and it offers all administration actions.

The JMX MBean is destroyed when the component stops.

Error management

If an error occurs during the creation of the JMX MBean:

  1. a message associated to the warning code 'SE-ASE-W0006' is logged with a WARNING level,
  2. no stack trace is logged.
  3. no administration JMX API will be available.

If an error occurs during the deletion of the JMX MBean:

  1. a message associated to the warning code 'SE-ASE-W0007' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the JMX MBean can exist always.
Relationsdepends on:
     CONT-JMX-API-010 : Naming convention of the MBean object names
     Status: Valid
blocks:
     SE-ASE-MON-000 : JMX API
     Status: Valid

Requirement: SE-ASE-ADM-005 : Identifying a persistence area
Scope

If an administration action needs to identify a persistence area, it uses the following both parameters:

  • local part of the target service name,
  • a value of the enumeration identifying the sub-type of the persistence area: PENDING (the persistence area associated to the incoming requests), EXPIRED (the persistence area associated to the incoming requests processed as expired), TIMEDOUT (the persistence area associated to the incoming requests processed as timed out), ERROR (the persistence area associated to the incoming requests processed with error), FAULT (the persistence area associated to the incoming requests processed with fault), ALL (all persistence areas).

JMX aspects

Parameters of the persistence area are available through the JMX operation as:

  • local part of the target service name, as String,
  • persistence area sub-type, as String.

Error management

If the persistence area to purge does not exist:

  1. a message associated to the error code 'SE-ASE-E0009' is logged with a ERROR level,
  2. no stack trace is logged.
  3. no purge is executed.
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0009: <msg-body>" where <msg-body> is the message logged in 1.

If the persistence area sub-type is invalid:

  1. a message associated to the error code 'SE-ASE-E0021' is logged with a ERROR level
  2. no stack trace is logged.
  3. no purge is executed.
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0021: <msg-body>" where <msg-body> is the message logged in 1.

 

Relationsrelated to:
     SE-ASE-ADM-010 : Purging a persistence area (In a next version)
     Status: Valid

Requirement: SE-ASE-ADM-010 : Purging a persistence area (In a next version)
Scope

An administration action is available to purge a persistence area destroying its all pending request.

The processing of purge starts to block internal processing waiting their end. During a persistence area purge, no more requests are persisted. Their processing waits the end of purge.

JMX aspects

This action is available through the JMX operation 'purge' with following parameters:

  • parameters to identify a persistence area,
  • list of message identifiers to purge, as String array. If null or empty, all requests are purged.

Error management

If an error occurs during the purge of a persistence area:

  1. a message associated to the error code 'SE-ASE-E0008' is logged with a ERROR level,
  2. no stack trace is logged,
  3. the purge is stopped,
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0008: <msg-body>" where <msg-body> is the message logged in 1.
Relationsrelated to:
     SE-ASE-ADM-005 : Identifying a persistence area
     Status: Valid

Requirement: SE-ASE-ADM-015 : Recycling a persistence area (In a next version)
Scope

An administrative action is available to recycle pending requests of a persistence area moving them to persistence area associated to incoming requests.

Note: Recycling the persistence area associated to the incoming request has no sens.

The processing to recycle starts to block internal processing waiting their end. During a persistence area recycling, no more incoming requests are persisted. Their processing waits the end of recycling.

Each request of the persistence area to recycle is saved into the persistence area of incoming requests. Their timestamp is updated to be set to the current timestamp.

JMX aspects

This action is available through the JMX operation 'recycle' with following parameters:

  • parameters to identify a persistence area,
  • boolean flag, as boolean value, to force the recycling if the target service is not idempotent,
  • list of message identifiers to recycle, as String array. If null or empty, all requests are recycled.

Error management

If the persistence area sub-type set is 'PENDING':

  1. a message associated to the error code 'SE-ASE-E0012' matching the following template is logged with a ERROR level,
  2. no stack trace is logged.
  3. no purge is executed.
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0012: <msg-body>" where <msg-body> is the message logged in 1.

If the target service is not an idempotent service, and the administrative action is not forced:

  1. a message associated to the error code 'SE-ASE-E0013' is logged with a ERROR level,
  2. no stack trace is logged.
  3. no purge is executed.
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0013: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs during the recycling:

  1. a message associated to the error code 'SE-ASE-E0018' is logged with a ERROR level,
  2. no stack trace is logged,
  3. the recycling is stopped,
  4. an error is returned to the caller with an error message as the following template: "ERROR SE-ASE-E0018: <msg-body>" where <msg-body> is the message logged in 1.

Requirement: SE-ASE-ADM-025 : Starting the posting process
Scope

An administrative action is available to start the posting process, persisting incoming request. See the related requirement.

JMX aspects

This action is available through the JMX operation 'startPostingProcess' without parameter.

Error management

If the posting process is already started:

  1. a message associated to the warning code 'SE-ASE-W0018' is logged with a WARNING level,
  2. no stack trace is logged,
  3. no start is launched,
  4. an error is returned to the caller with an error message as the following template: "WARNING SE-ASE-W0018: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs during the start of the posting process:

  1. see related requirement,
  2. an error is returned to the caller with the error message of the related requirement.

 

Relationsrelated to:
     SE-ASE-PROC-006 : Starting the posting process
     Status: Valid

Requirement: SE-ASE-ADM-020 : Stopping the posting process
Scope

An administrative action is available to stop the posting process, no more incoming request will be persisted. See the related requirement.

JMX aspects

This action is available through the JMX operation 'stopPostingProcess' without parameter.

Error management

If the posting process is already stopped:

  1. a message associated to the warning code 'SE-ASE-W0019' is logged with a WARNING level,
  2. no stack trace is logged,
  3. no stop is launched,
  4. an error is returned to the caller with an error message as the following template: "WARNING SE-ASE-W0019: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs during the stop of the posting process:

  1. see the related requirement,
  2. an error is returned to the caller with the error message of the related requirement.

 

Relationsrelated to:
     SE-ASE-PROC-051 : Stopping the posting process
     Status: Valid

Requirement: SE-ASE-ADM-035 : Starting the sending process
Scope

An administrative action is available to start the sending process to listen persisted requests listener. See the related requirement.

JMX aspects

This action is available through the JMX operation 'startSendingProcess' without parameter.

Error management

If the sending process is already started:

  1. a message associated to the warning code 'SE-ASE-W0021' is logged with a WARNING level,
  2. no stack trace is logged,
  3. no start is launched,
  4. an error is returned to the caller with an error message as the following template: "WARNING SE-ASE-W0021: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs during the start of the sending process:

  1. see the related requirement,
  2. an error is returned to the caller with the error message of the related requirement.

 

Relationsrelated to:
     SE-ASE-PROC-007 : Starting the sending process
     Status: Valid

Requirement: SE-ASE-ADM-030 : Stopping the sending process
Scope

An administrative action is available to stop the sending process, persisted requests will not be processed. See the related requirement.

JMX aspects

This action is available through the JMX operation 'stopSendingProcess' without parameter.

Error management

If the sending process is already stopped:

  1. a message associated to the warning code 'SE-ASE-W0020' is logged with a WARNING level,
  2. no stack trace is logged,
  3. no stop is launched,
  4. an error is returned to the caller with an error message as the following template: "WARNING SE-ASE-W0020: <msg-body>" where <msg-body> is the message logged in 1.

If an error occurs during the stop of the sending process:

  1. see the related requirement,
  2. an error is returned to the caller with the error message of the related requirement.
Relationsrelated to:
     SE-ASE-PROC-052 : Stopping the sending process
     Status: Valid

1.4. Requirements Spec.: SE-ASE-MONITORING : Monitoring
Scope

Requirement: SE-ASE-MON-000 : JMX API
Scope

Monitoring information are available through JMX using the same MBean as administration.

Relationsdepends on:
     SE-ASE-ADM-001 : JMX API
     Status: Valid

Requirement: SE-ASE-MON-005 : Monitoring the persistence areas
Scope

The customer is responsible to monitor the persistence areas through the persistence system using the appropriate tools, as Nagios. The component has not to monitor persistence areas.


Requirement: SE-ASE-MON-010 : Monitoring the connection to the persistence system (In a next version)
Scope

The current status of the connection to the persistence system is kept.

It is updated:

  • on each interaction with the persistence system,
  • if there is no activity, by a periodic connection try.

JMX aspects

The current status of connection is available through the MBean attribute 'connectionStatus'.


Requirement: SE-ASE-000 : Installing the component
Scope

Component parameters are checked during the component installation, before to start it.

Component parameter values are logged with a CONFIG level.

Error management

If the component parameter associated to the initial context factory class name is missing or empty:

  1. a message associated to the error code 'SE-ASE-E0002' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component installation is aborted.

If the initial context factory class is not found in the component class loader:

  1. a message associated to the error code 'SE-ASE-E0003' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component installation is aborted.

If the component parameter associated to the JNDI provider URL is missing or empty:

  1. a message associated to the error code 'SE-ASE-E0004' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component installation is aborted.

If the component parameter associated to the JNDI provider URL is malformed:

  1. a message associated to the error code 'SE-ASE-E0015' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component installation is aborted.

If the component parameter associated to the name of the JMS connection factory is missing or empty:

  1. a message associated to the error code 'SE-ASE-E0005' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component installation is aborted.

If the value of the parameter associated to the TTL is not an integer number value:

  1. a message associated to the warning code 'SE-ASE-W0014' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the TTL is defined according to the default value of parameter TTL.

If the value of the parameter associated to the stop timeout is not an integer number value:

  1. a message associated to the warning code 'SE-ASE-W0015' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the default value of stop timeout is used.

 


Requirement: SE-ASE-010 : Starting the component
Scope

The connection to the persistence server is realized during the start of the component.

A message is logged with an CONFIG level to trace the configuration parameter values needed to the connection to the persistence server.

Error management

If an error occurs during the connection to the persistence server:

  1. a message associated to the error code 'SE-ASE-E0006' is logged with an ERROR level,
  2. no stack trace is logged.
  3. the component startup is aborted.

Requirement: SE-ASE-020 : Stopping the component
Scope

The connection to the persistence server is released.

All service units are stopped.

Error management

If an error occurs during the disconnection to the persistence server:

  1. a message associated to the warning code 'SE-ASE-W0008' is logged with a WARNING level,
  2. no stack trace is logged.
  3. the component stop continues.
Relationsrelated to:
     SE-ASE-PROC-050 : Stopping a service unit
     Status: Valid

Requirement: SE-ASE-ERRORS : Error messages
Scope

The component defines following error messages:

Error code Message template
SE-ASE-E0001 "An error occurs creating the persistence area '<persistence-area-name>': <error-msg>." where <persistence-area-name> is the name of the persistence area for which the creation fails and <error-msg> is the error returns by the persistence system.
SE-ASE-E0002 "The mandatory parameter 'JNDI Initial Context Factory' is not set".
SE-ASE-E0003 "JNDI Initial Context Factory not found: <class-name>.", where <class-name> is the initial context factory class name.
SE-ASE-E0004 "The mandatory parameter 'JNDI provider URL' is not set".
SE-ASE-E0005 "The mandatory parameter 'Name of the JMS Connection Factory' is not set".
SE-ASE-E0006 "An error occurs during the connection to the persistence service: <reason>." where <reason> is the reason why the connection fails.
SE-ASE-E0007 "An error occurs removing a request from the persistence area '<persistence-area-name>': <reason>." where <persistence-area-name> is the name of the persistence area for which the request removing fails and <reason> is the reason why the request removing fails.
SE-ASE-E0008 "An error occurs purging the persistence area <persistence-area-name>: <reason>." where <persistence-area-name> is the name (and sub-type) of the persistence area to purge and <reason> is the reason why the purge fails.
SE-ASE-E0009 "The persistence area '<persistence-area-name>' does not exist." where <persistence-area-name> is the name (and sub-type) of the persistence area to use with the administrative action.
SE-ASE-E0010 "Only one-way request (InOnly or RobustInOnly) are supported. Received MEP: <mep-pattern>." where <mep-pattern> is the pattern of the received request.
SE-ASE-E0011 "An error occurs saving a request in the persistence area '<persistence-area-name>': <reason>." where <persistence-area-name> is the name of the persistence area for which the save of the request fails and <reason> is the reason why the request saving fails.
SE-ASE-E0012 "The persistence area '<persistence-area-name>' with sub-type PENDING can not be recycled." where <persistence-area-name> is the name of the persistence area to recycle.
SE-ASE-E0013 "The target service provider is not idempotent. Use the boolean flag to force the recycling of the persistence area '<persistence-area-name>'." where <persistence-area-name> is the name of the persistence area to recycle.
SE-ASE-E0015 "The mandatory parameter 'JNDI provider URL' is malformed".
SE-ASE-E0017 "A request 'request-id' cannot be processed because of timeout on target service invocation. The request is moved the queue '<queue-name>'." where <request-id> is the message exchange identifier of the request, and <queue-name> is the queue name of persisted requests processed with a timeout.
SE-ASE-E0018 "An error occurs recycling the persistence area <persistence-area-name>: <reason>." where <persistence-area-name> is the name (and sub-type) of the persistence area to purge and <reason> is the reason why the purge fails.
SE-ASE-E0019 "An error occurs starting the posting process: <reason>. Unexpected error can occurs next." where <reason> is the reason why the start fails.
SE-ASE-E0020 "A request 'request-id' cannot be processed because of an error on target service invocation. The request is moved the queue '<queue-name>'." where <request-id> is the message exchange identifier of the request, and <queue-name> is the queue name of persisted requests processed with error.
SE-ASE-E0021 "The persistence area '<persistence-area-name>' is provided with an invalid sub-type. Only following sub-type are supported: PENDING, EXPIRED, TIMEDOUT, ERROR, FAULT and ALL" where <persistence-area-name> is the name (and sub-type) of the persistence area to purge.
SE-ASE-E0022  "The parameter '<parameter-name>' is defined twice with different values in both sections 'consumes' and 'provides' of the JBI service unit descriptor. It should be declared once." where <parameter-name> is the name of the parameter defining a queue name.

 


Requirement: SE-ASE-INFOS : Information messages
Scope

The component defines following error messages:

Error code Message template
SE-ASE-I0001 "The posting process is started."
SE-ASE-I0002 "The sending process is started."
SE-ASE-I0003' "The posting process is stopped."
SE-ASE-I0004 "The sending process is stopped."

 


Requirement: SE-ASE-WARNS : Warning messages
Scope

The component defines following warning messages:

Warning code Message template
SE-ASE-W0001  "Two sections 'provides' are declared in the JBI descriptor of the service-unit '<su-name>' instead of only one. Unexpected error can occur" where <su-name> is the name of the service-unit.
SE-ASE-W0002  "Two sections 'consume' are declared in the JBI descriptor of the service-unit '<su-name>' instead of only one. Unexpected error can occur" where <su-name> is the name of the service-unit.
SE-ASE-W0003 "Interface name of both sections 'consume' (<itf-consume>) and 'provide' (<itf-provide>) are different. '<itf-consume>' is used as interface name of the section 'provide'." where <itf-consume> is the interface name declared in the section 'consume' and <itf-provide> is the interface name declared in the section 'provide'.
SE-ASE-W0004 "An error occurs creating the persisted request listener: <reason>. No administrative JMX API will be available." where <reason> is the reason why the persisted request listener cannot be created.
SE-ASE-W0006 "An error occurs during the creation of the administration JMX API: <reason>." where <reason> is the reason why the creation fails.
SE-ASE-W0007 "An error occurs during the deletion of the administration JMX API: <reason>. Unexpected error can occur using the administration JMX API." where <reason> is the reason why the deletion fails.
SE-ASE-W0008  "An error occurs during the disconnection to the persistence system: <reason>." where <reason> is the reason why the disconnection fails.
SE-ASE-W0009 "An error occurs stopping the posting process: <reason>. Incoming requests may be processed." where <reason> is the reason why the posting process cannot be stopped.
SE-ASE-W0010 "An error occurs stopping the sending process: <reason>. Persisted request may be sent to the target service provider." where <reason> is the reason why the sending process cannot be stopped.
SE-ASE-W0011 "The TTL of a request is expired. The request was moved to the persistence area '<expired-persistence-area>'." where <expired-persistence-area> is the name of the persistence area containgin expired requests.
SE-ASE-W0012 "The parameter '<parameter-name>' is defined twice with the same value in both sections 'consumes' and 'provides' of the JBI service unit descriptor. It should be declared once." where <parameter-name> is the name of the parameter defining a queue name.
SE-ASE-W0013 "Invalid boolean value 'invalid-value' for parameter 'is-idempotent'. Default value used: <default-value>." where <invalid-value> is the invalid boolean value declared in the section 'consumes' and <default-value> is the default value of parameter 'is-idempotent'.
SE-ASE-W0014 "Invalid integer number value 'invalid-value' for parameter 'time-to-live'. Default value used: <default-value>." where <invalid-value> is the invalid integer number value declared in the section 'consumes' and <default-value> is the default value of parameter 'time-to-live'.
SE-ASE-W0015 "Invalid integer number value 'invalid-value' for parameter 'stop-timeout'. Default value used: <default-value>." where <invalid-value> is the invalid integer number value and <default-value> is the default value of parameter stop timeout.
SE-ASE-W0016 "Retry policy configuration and TTL are not compliant. TTL is increased to <new-ttl-value> to be compliant with the retry policy." where <new-ttl-value> is a new value of the TTL compliant with the retry policy.
SE-ASE-W0017 "The optional parameter 'mustBeAutomaticallyStarted' has not a boolean value. The default value (<default-value>) is used", where <default-value> is the parameter default value.
SE-ASE-W0018 "The posting process is already started. Operation aborted."
SE-ASE-W0019 "The posting process is already stopped. Operation aborted."
SE-ASE-W0020 "The sending process is already stopped. Operation aborted."
SE-ASE-W0021 "The sending process is already started. Operation aborted."
SE-ASE-W0022 "A technical error occurs when invoking the target service invokation on request 'request-id'. Waiting for <duration> seconds before next try (<try>/<try-number>)." where <request-id> is the message exchange identifier of the request, <duration> is the duration of the interval, in seconds, between invocations, <try> is the number of the next try and <try-number> is the maximum number of tries.
SE-ASE-W0023 "An error occurs starting the sending process: <reason>." where <reason> is the reason why the sending process cannot be started.
SE-ASE-W0024  "Timeout on target service invocation on request 'request-id'. Waiting for <duration> seconds before next try (<try>/<try-number>)." where <request-id> is the message exchange identifier of the request, <duration> is the duration of the interval, in seconds, between invocations, <try> is the number of the next try and <try-number> is the maximum number of tries.