JOSIF Main Page | JOSIF Framework | TIP Soap Generator | External XSD

Motivation and Requirements

Motivation

Some specifications are defined in external schemas that is necessary to reuse in JOSIF environment. In principle, one could re-model entities already defined by existing XML schemas during the information or operational modeling phase once again and then run the JOSIF engine. This, however, would result in schemas that merely “re-invent” objects already defined elsewhere. Moreover, current JOSIF generators set namespaces different from those assigned to the existing XML schemas. Both issues entail problems in terms of compliance of new interface definitions to existing XML schemas and regarding available implementations of those existing XML schemas. So we must avoid redefining these objects and namespaces in the JOSIF modeling. An easy way to perform the configuration must be supported and also must care about the possibility of include several external references.

Requirements

To include this behaivour a new stereotype is defined, proxy with prefix, namespace and location attributes in TIP profile. The inclusion of elements or complex types from the external schema is supported by empty artifacts that acts as a container. For these artifacts generation is not performed and only the reference to the external schema is included in the generated documents. In the generation also the definition of the external schema and import from the location will be included.

To speed up the modeling stage, the defintion of proxy sterotype could be defined in package artifacts and the definition will be shared by all artifacts contained in the package. All artifacts contained use the same proxy definition included in its container.

The name validation of external schema looks to the internet to import XSD definitions from locations specified in the new stereotypes. In the properties it can setup a catalog of local copies of the schemas. The standard way to do this is to use a catalog.xml file which maps the referenced remote location to the local defition. XML Catalogs.

Functionality

Options

These are specific options related with the support of external schemas.

Deployment

The support of external XSDs is only present in JOSIF version 1.2. It uses the proxy stereotype included in th TIP_Profile. The stereotype has four attributes:

• comment: Comments to help in documentation
• prefix: Prefix used by the external schema reference in the documents generated
• namespace: Namespace used by the external schema reference in the documents generated
• location: Location used by the external schema reference in the documents generated

Catalog

The schemas could be accesed by their http address, but sometimes is not possible to achieve documents in Internet. To solve this issue, a XML Catalog could be setup. In the dependencies project, the folder externalxsds will contain the catalog file called external-dependencies-catalog.xml and a subfolder labeled schemas where the external XSDs will be stored

Now we can see an example of the catalog configuration file  external-dependencies-catalog.xml

Example of catalog file

<?xml version="1.0" encoding="UTF-8"?>
<catalog
  xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteSystem
    systemIdStartString="http://docs.oasis-open.org/security/saml/v2.0/saml-schema-protocol-2.0.xsd"
    rewritePrefix="schemas/saml-schema-protocol-2.0.xsd"/>
  <rewriteSystem
    systemIdStartString="http://docs.oasis-open.org/security/saml/v2.0/saml-schema-assertion-2.0.xsd"
    rewritePrefix="schemas/saml-schema-assertion-2.0.xsd"/>
  <rewriteSystem
    systemIdStartString="http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd"
    rewritePrefix="schemas/xmldsig-core-schema.xsd"/>
</catalog>

Package

To add a new external schema we need to include a new package in the dependency project. This package must be configured with a stereotype proxy where the attributes prefix, namespace and location must be filled. This information is the definition of the external schema.

Element

Inside the package we can add the types, elements or complex types used in the external schema and define an empty artifact to support the mapping. We can define all the elements that we need and after that we can export the dependency project and update the Model project. In the model project you can use the new dependency elements (sometimes the eclipse cache doesn't work well and you need to restart the eclipse environment) in the arguments of the operations that you consider.

Generation

Then via the build process or using the generation button in Tigerstripe, you could perform the SOAP generation and if it ends correctly then check the log files to see a non stop error and the xsds and wsdl files generated to validate the process

Error management

In the use of proxy stereotype in JOSIF modeling, there are some constraints associated with the configuration that must be considered as errors. There are two types: generation stop errors and logged errors.

• The first one type is a set of errors that stops the generator and publish the error in the log file:
  • Object not in schema: When the validation of schema is activated and the name of the element is not found in the external schema
  • Object already defined: When a non empty artifact is included in a package with the proxy sterotype behaivour

• The second one is detected and then logged as an ERROR:
  • An error is logged if a proxied element has its own definition
  • An error is logged if several proxys are defined for an artifact
  • An error is logged if prefix is not unique
  • An error is logged if a bad URL or emtpy attributes are detected

Documentation

When we include some external XSD in the models, we need to document this information in the Interface Agreements generated by the Doc Generator. Each element is defined in its table at the properties column as:

External argument:

-namespace: Namespace information gathered from the proxy stereotype in the scope (package or individual)

-prefix: Prefix information gathered from the proxy stereotype in the scope (package or individual)

-comments: Comments information gathered from the proxy stereotype in the scope (package or individual)

Example

We now illustrate the process of use external XSDs with an example using the ESEC team project, adding a stereotype at package level. TIP_SII_SG_EXTERNAL XSD_V0-1.doc