WS_CONFIGURE

Context for use

SOAP or Restful Web Service production.

Section for use

DECLARATION of the program

DECLARATION of a public procedure

Syntax

WS_CONFIGURE Scope ConfigElem

Description

This instruction configures the behaviour of SOAP Web service (DOCUMENT or DOCUMENT_JAXWS style) or a RESTful Web service produced with Adelia Studio. The configuration items relate either to the Web service or to one of its operations (the operation containing the instruction in question).

For SOAP Web Service, the configuration items are added to the "services.xml" file in the <ServiceName.aar> archive containing all the constituent elements of the DOCUMENT/Literal-type Web service.

For a RESTful Web service, configuration items are taken into account in generating the 3GL source, mostly in the form of Java annotations.

There are two ways of adding a configuration item:

Add an AttributeName / AttributeValue pair

- Certain predefined attribute names make it easy to configure the most common options:

WS_CONFIGURE *SERVICE 'jaxws_itemlist_name' 'item_<list>'
LIST lst z1 z2
PARAM lst,i,listIn

<listIn>
   <item_listIn><z1>value</z1><z2>value</z2></item_listIn>
   <item_listIn><z1>value</z1><z2>value</z2></item_listen>
   ...
</listIn>

LIST lst z1 z2
PARAM lst,i,mylist

<mylist>
   <mylists>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylists>
<mylist> 

<mylist>
   <mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      <mylist><z1>value</z1><z2>value</z2></mylist>
      ...
   </mylist>
<mylist> 

ALPHA(15) p1
LIST lst z1 z2
PARAM p1,o,palp lst,o,mylist 

<palp>value</palp>
<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 

<palp>value</palp>
<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...

LIST lst z1 z2
PARAM lst,i,mylist 

<mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   <mylist><z1>value</z1><z2>value</z2></mylist>
   ...
<mylist> 

<mylist><z1>value</z1><z2>value</z2></mylist>
<mylist><z1>value</z1><z2>value</z2></mylist>
...

Notes:

• • • For REST services, autocomplete suggests predefined constants (_WS_REST_FMT_*) for the most common exchange formats; these constants must be used with @Produces or @Consumes attributes.
    • For a SOAP Web service, the other attribute names generate a configuration XML element called 'parameter': <parameter name="AttributeNames">AttributeValue</parameter>.

Warning:

• • • SOAP/DOCUMENT_JAXWS - setting the target_namespace and schema_namespace attributes with different values can produce an incomplete result when automatically registering the web service: the response element ('<Operation>Return') of an operation can therefore be abnormally presented as a final element.

Add an XML extract from an ALPHA constant (*XML_MEM) or Adelia resource (*XML_FILE) (Only SOAP).

The Axis2 functions that Adelia Studio is based on are expandable by using modules which are implementations of the different standardized specifications linked to the Web services (WS-*). For example, the "rampart" module is an implementation of the WS-SECURITY specification in charge of Web services security.

For each of these modules, refer to the documentation available on the internet to find out the available configuration items which can be inserted in the service's services.xml configuration file.

Directives *XML_MEM and *XML_FILE are used to add configuration items to the services.xml file in full.

For example

SOAP

WS_CONFIGURE *SERVICE 'target_namespace' 'http://mondomain.com'

Redefines the service's target_namespace.

WS_CONFIGURE *SERVICE 'module' 'addressing'

Commits the addressing module (WS_ADDRESSING)

WS_CONFIGURE *SERVICE 'scope' 'application'

Declares an 'application'-scope service.

WS_CONFIGURE *SERVICE 'enableMTOM' 'true'

Activates MTOM optimization for transmission of binary data by the service.

WS_CONFIGURE *SERVICE *XML_FILE(SecPolicy)

Adds an XML extract from an Adelia resource called SecPolicy.

REST

A resource (public procedure) of a RESTful service is addressable via a URI and an action (HTTP method).

The URI is defined using the  @Path attribute; the HTTP methods are defined using @GET,  @PUT, @POST, @DELETE, @HEAD, @OPTIONS attributes .

WS_CONFIGURE *SERVICE '@Path' '/cars'

WS_CONFIGURE *SERVICE _WS_REST_A_PATH '/cars'

Defines an @Path annotation for the program (or service; defining the root resource).

WS_CONFIGURE *OPERATION '@Path' '/{numberPlate}'

WS_CONFIGURE *OPERATION _WS_REST_A_PATH  '/{numberPlate}'

Assigns an @Path annotation for a public procedure (resource).

The URI may contain variable parts (a variable is enclosed in braces); to be usable, these variables must match the local parameters of the public procedure.

WS_CONFIGURE *OPERATION '@GET' *BLANK

WS_CONFIGURE *OPERATION _WS_REST_A_GET *BLANK

Assigns an @Path action (HTTP method) for a public procedure (resource).

WS_CONFIGURE *OPERATION '@Consumes' 'application/xml;charset=utf-8'

WS_CONFIGURE *OPERATION _WS_REST_A_CONSUMES _WS_REST_FMT_APP_XML

Defines a format accepted for management of the body/content of the HTTP query.

WS_CONFIGURE *OPERATION '@Produces' 'application/json'

WS_CONFIGURE *OPERATION _WS_REST_A_PRODUCES _WS_REST_FMT_APP_JSON

Defines an format produced for management of the body/content of the HTTP request.

The same resource can return content in several formats to adapt to customer preferences (expressed via the HTTP accept header).

Authorization management

WS_CONFIGURE *SERVICE '@DeclareRoles' 'role1,role2,role3'
WS_CONFIGURE *SERVICE _WS_REST_A_DECLARE_ROLES 'role1,role2,role3'
Declaration of roles used in authorization management.

WS_CONFIGURE *OPERATION '@RolesAllowed' 'role1'
WS_CONFIGURE *OPERATION _WS_REST_A_ROLES_ALLOWED 'role1,role3'
Definition of roles authorized to access the resource.

WS_CONFIGURE *OPERATION '@PermitAll' *BLANK
WS_CONFIGURE *OPERATION _WS_REST_A_PERMIT_ALL *BLANK 
Grants access to the resource to all roles defined via the @DeclareRoles annotation.

WS_CONFIGURE *OPERATION '@DenyAll' *BLANK
WS_CONFIGURE *OPERATION _WS_REST_A_DENY_ALL *BLANK 
Deletes resource access for all roles.

Swagger

WS_CONFIGURE *SERVICE '_swag_extdoc_url' 'http://www.doc.externe'
WS_CONFIGURE * SERVICE _WS_REST_SWAG_EXTERNAL_DOC_URL 'http://www.doc.externe '
A link to external documentation has been added.

WS_CONFIGURE * SERVICE '_swag_extdoc_desc' 'Link to external documentation'
WS_CONFIGURE * SERVICE _WS_REST_SWAG_EXTERNAL_DOC_DESC 'Link to external documentation'
A description of the link to external documentation has been added.

WS_CONFIGURE *SERVICE '_swag_tags' Group1,Group2'
WS_CONFIGURE *SERVICE _WS_REST_SWAG_TAGS 'Group1,Group2'
Declaration of groups used to present the service's resources.

WS_CONFIGURE *SERVICE '_swag_description' 'Description Group1,Description Group2'
WS_CONFIGURE *SERVICE _WS_REST_SWAG_DESCRIPTION 'Description Group1,Description Group2'
Declaration of descriptions of groups used to present the service's resources.

WS_CONFIGURE *OPERATION '_swag_tags' Group1'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_TAGS 'Group1'
Assignment of the resource to the group called Group1.

 
WS_CONFIGURE *OPERATION '_swag_description' 'Description of the resource'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_DESCRIPTION 'Description of the resource'
Association of a description with the resource.

WS_CONFIGURE *OPERATION '_swag_notes' 'Extended description of the resource'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_NOTES 'Extended description of the resource'
Association of an extended description with the resource.

WS_CONFIGURE *OPERATION '_swag_desc_param' 'Param1Name:Description of param1'
WS_CONFIGURE *OPERATION '_swag_desc_param' 'Param2Name:Description of param2'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_DESC_PARAM 'Param1Name:Description of param1'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_DESC_PARAM 'Param2Name:Description of param2'
Association of a description with a resource input parameter.

WS_CONFIGURE *OPERATION '_swag_response' '404:Resource not found'
WS_CONFIGURE *OPERATION '_swag_response' '403:Unauthorized resource access'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_RESPONSE '404:Resource not found'
WS_CONFIGURE *OPERATION _WS_REST_SWAG_RESPONSE '403:Unauthorized resource access'

WS_CONFIGURE  *OPERATION '_ swag_response ' 'VarPerson:200:The person has been correctly identified'
WS_CONFIGURE  *OPERATION '_ swag_response ' 'VarError:500:Error while executing the service'
WS_CONFIGURE  *OPERATION '_ swag_response ' '*NONE:401:User is not authorized'
Provides a description of the possible HTTP codes linked to the resource.

↑ Top of page