|
VADELIA |
|
EADELIA |
|
(B) (C) |
(B) (C) |
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
Scope |
→ |
*SERVICE | *OPERATION |
ConfigElem |
→ |
ValueAttribute | ExtractXml |
ValueAttribute |
→ |
AttributeName AttributeValue |
AttributeName |
→ |
'AlphaConstant' |
AttributeValue |
→ |
'AlphaConstant' |
ExtractXml |
→ |
*XML_MEM(XmlMem) | *XML_FILE(XmlFile) |
XmlMem |
→ |
'AlphaConstant' |
XmlFile |
→ |
AdeliaResourceName |
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:
AttributeName |
Scope |
Description |
Type |
target_namespace |
*SERVICE |
Redefines the service's target_namespace. |
SOAP |
schema_namespace |
*SERVICE |
Defines a specific schema_namespace for the items of the produced XML schema. |
SOAP |
scope |
*SERVICE |
Defines the scope of the service ('request', 'soapsession', 'transportsession', 'application') ; 'request' is the default scope. 'soapsession' and 'transportsession' are scopes specific to the type of SOAP service. |
SOAP or REST |
elementFormDefault |
*SERVICE |
Sets the information elementFormDefault to qualified (by default) or unqualified for the generation of the XML schema in the produced WSDL file. |
SOAP |
attributeFormDefault |
*SERVICE |
Sets the information attributeFormDefault to qualified (by default) or unqualified for the generation of the XML schema in the produced WSDL file. |
SOAP |
schemaDisableNillableElem |
*SERVICE |
Deactivates (true) the "nillable" items, for the generation of the XML schema in the produced WSDL file. |
SOAP |
schemaDisableOptionalElem |
*SERVICE |
Deactivates (true) the optional items (attribute "minoccurs=0") for the generation of the XML schema in the produced WSDL file. |
SOAP |
action_mapping |
*OPERATION |
Adds a specific action_mapping for the operation. |
SOAP |
async |
*SERVICE | *OPERATION |
Allows an asynchronous service to be declared (true | false). |
SOAP |
module |
*SERVICE | *OPERATION |
Allows a module to be engaged. |
SOAP |
enableMTOM |
*SERVICE |
Enabling MTOM optimization for the transfer of binaries towards the customer. (true | false) Binaries are then no longer serialized as a base 64 encoded string but in the form of MTOM optimized mime messages. |
SOAP |
@Path |
*SERVICE | *OPERATION |
Assigning a URI to a program (root resource) or a public procedure (resource). If the URI contains variables {var}, the latter, in order to be used, must be declared as parameters. |
REST |
@GET @PUT @POST @DELETE @OPTIONS @HEAD |
*SERVICE | *OPERATION |
Assigning an HTTP operation to a public procedure (resource). |
REST |
@Consumes |
*SERVICE | *OPERATION |
Defining formats accepted by a resource. The format is that of the body of the HTTP query. |
REST |
@Produces |
SERVICE | *OPERATION |
Defining formats produced by a resource. The format is that of the body of the HTTP answer. |
REST |
_init_pgm_as_method |
*SERVICE |
Defining INIT_PGM block behavior. (true | false) By default (true), the INIT_PGM block is treated as a public procedure in order to become a resource. If the attribute is set to "false", the INIT_PGM block is no longer a resource, but a service initialization block. This is useful in the case of a service with an "application" scope. |
SOAP or REST |
_root_result_name |
*OPERATION |
Makes it possible, for the serialization process, to name a set built from several parameters of the content type. |
SOAP or REST |
_swag_description |
*SERVICE | *OPERATION |
Addition of a swagger description to a public procedure (resource). In the case of a *SERVICE (root resource) range, the Adelia program description is used by default. Defines a group/tag which is common to all service operations/APIs. |
REST |
_swag_tags |
*SERVICE | *OPERATION |
In the case of a *SERVICE scope, defines the service's groups/tags. The separator is a comma. |
REST |
_swag_notes |
*OPERATION |
Addition of an extended swagger description to a public procedure (resource). |
REST |
_swag_desc_param |
*OPERATION |
Addition of a swagger description specific to a path, query, header or form input parameter. By default: the parameter's external name is used if there is one or the internal name if necessary. The attribute value is made up of two parts separated by the character ':'. The first part is the parameter name and the second part is the description. Example: ws_configure *OPERATION '_swag_desc_param' 'idPers:identifier of a person' |
REST |
_swag_response |
*OPERATION |
Used to present the possible HTTP return codes. The attribute value is made up of two parts separated by the character ':'. The first part is the HTTP code and the second part is the description. Example: ws_configure *OPERATION '_swag_response' '404:the requested resource was not found' |
REST |
_swag_extdoc_url |
*SERVICE |
Used to add a link to external documentation. A description using the attribute _swag_extdoc_desc needs to be added in order to display the link. Example: ws_configure *SERVICE '_swag_extdoc_url' 'http://www.hardis-group.com' |
REST |
_swag_extdoc_desc |
*SERVICE |
Used to add a description describing the link to external documentation. Example: ws_configure *SERVICE '_swag_extdoc_desc' 'Hardis Group' |
REST |
@DeclareRoles |
*SERVICE |
Declares a set of roles which are useful for secure management by resource annotation (comma separator). |
REST |
@PermitAll |
*SERVICE | *OPERATION |
Grants access to the resource to all the roles defined via the @DeclareRoles annotation. |
REST |
@RolesAllowed |
*SERVICE | *OPERATION |
Grants access to the resource to all the roles specified in the annotation (comma separator): the input roles must belong to all the roles declared via the @DeclareRoles annotation. |
REST |
@DenyAll |
*SERVICE | *OPERATION |
Prohibits all roles from accessing the resource. |
REST |
Note: For the REST web services, the auto-complete function suggests predefined constants (_WS_REST_FMT_*) for the most common exchange formats. These constants should be used with the @Produces or @Consumes attributes.
- For SOAP Web Service, the other attribute names generate an XML configuration item called 'parameter': <parameter name="AttributeName">AttributeValue</parameter>.
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'
Provides a description of the possible HTTP codes linked to the resource.