Chapter 1: ServiceMap Document: A Simple Example

• Specify the namespace for the document and your service: In the example below, "http://www.extreme.indiana.edu/services/simpleService"  is the namespace for your service

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/gFac"
            xmlns:simpleService="http://www.extreme.indiana.edu/services/simpleService">
</ServiceMap>

• Specify a name and a description for your service

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/gFac"
            xmlns:simpleService="http://www.extreme.indiana.edu/services/simpleService">

    <service>
        <serviceName targetNamespace="http://www.extreme.indiana.edu/services/simpleService">SimpleService</serviceName>
        <serviceDescription>A simple service that lists the files in the given directory</serviceDescription>
    </service>

</ServiceMap>

• Specify the methods (a.k.a operations) supported by your service: Although the ServiceMap schema supports multiple portTypes, the Generic Application Factory that creates the application services supports only one portType per service. A portType is similar to the "WSDL port-type". A portType can have several operations. Each operation has a name, a description, and an application associated with it. When a client invokes an operation on a service, the service runs the associated application. All the input parameters to the operation along with their values are passed on to the application. Operation names cannot have blank spaces or special characters in them. The application element has an application name which has a targetNamespace attribute. The application name along with its targetNamespace uniquely identifies an application and is the fully qualified name for that application. The deployment description of the application is specified in a separate XML document that we call the ApplicationDescription document and is described later.

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/gFac"
            xmlns:simpleService="http://www.extreme.indiana.edu/services/simpleService">

    <service>
        <serviceName targetNamespace="http://www.extreme.indiana.edu/services/simpleService">SimpleService</serviceName>
        <serviceDescription>A simple service that lists the files in the given directory</serviceDescription>
    </service>

    <portType>
        <method>
            <!-- Method names cannot have special characters like blank spaces in them -->
            <methodName>List</methodName>
            <methodDescription> List files in the given directory </methodDescription>

            <application>
                <applicationName targetNamespace="http://www.extreme.indiana.edu/application/simpleApplication">LS-Application</applicationName>
                <description>This application lists the files in a directory</description>
            </application>   
        </method>
    </portType>
   
</ServiceMap>

As we mentioned before, when a client invokes an operation on a service, the services runs the associated application and all the input parameters along with their values are passed on to the application. If you don't want the input parameter names to be passed on to the application and want just the input parameter values to be passed on to the application, then you must use the attribute "paramValuesOnly=true" in the "application" element as shown below.

<application paramValuesOnly="true">
    <applicationName targetNamespace="http://www.extreme.indiana.edu/application/simpleApplication">LS-Application</applicationName>
    <description>This application lists the files in a directory</description>
</application>

• Specify the input parameters to a method: You must specify all the input parameters to the application using the inputParameter element. If the method does not take an input parameter then you should not specify one. You should have as many inputParameter elements as there are input parameters to your application. The inputParameter element has a parameter name, parameter description, and parameter type.

• parameterName: This is the name of the input parameter.  It must not contain any blank space or special characters. However, it can start with a minus (-) character.

• parameterDescription: This is a short description of the parameter.

• parameterType: This is the data type of the input parameter. Supported data types for input parameters are
  

  • String: A string value
  • Integer: An integer value
  • Float: A float value
  • Double: A double value
  • Boolean: A boolean value
  • QName: A fully qualified name
  • URI: A URI
  • StringArray: An unbounded array of strings
  • IntegerArray: An unbounded array of integers
  • FloatArray: An unbounded array of floats
  • DoubleArray: An unbounded array of doubles
  • BooleanArray: An unbounded array of boolean values
  • URIArray: An unbounded array of URIs
  • QNameArray: An array of QNames
  • StringEnum: An enumeration of string values
  • IntegerEnum: An enumeration of integer values
  • FloatEnum: An enumeration of float values
  • DoubleEnum: An enumeration of double values
  • LEADNameListFile: A URI that represents a FORTRAN namelist file used to specify input parameters to LEAD applications
    
  • LEADFileID: A String that represents a unique identifier for data products produced and consumed by LEAD applications
    
  • LEADFileIDArray: An array of LEADFileIDs
  • LEADNameListPropertiesFile: A Java properties file having a list of name value pairs that need to be updated in the LEADNameListFile with the values provided by the user during the service invocation
    

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/gFac"
            xmlns:simpleService="http://www.extreme.indiana.edu/services/simpleService">

    <service>
        <serviceName targetNamespace="http://www.extreme.indiana.edu/services/simpleService">SimpleService</serviceName>
        <serviceDescription>A simple service that lists the files in the given directory</serviceDescription>
    </service>

    <portType>
        <method>
            <!-- Method names cannot have special characters like blank spaces in them -->
            <methodName>List</methodName>
            <methodDescription> List files in the given directory </methodDescription>

            <application>
                <applicationName targetNamespace="http://www.extreme.indiana.edu/application/simpleApplication">LS-Application</applicationName>
                <description>This application lists the files in a directory</description>
            </application>

            <inputParameter>
                <parameterName>directoryName</parameterName>
                <parameterType>String</parameterType>
                <parameterDescription>This name of the directory that has to be listed</parameterDescription>
            </inputParameter>

        </method>
    </portType>

</ServiceMap>

Specify the output parameters of the method: You must specify at least one output parameter for a method. The output parameter is the output result when the application is invoked. If you want the entire standard out of the application as the value of the output parameter, the "parameterType" for the output parameter must be “StdOut”. A list of supported output parameter types are listed below

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/gFac"
            xmlns:simpleService="http://www.extreme.indiana.edu/services/simpleService">
    <service>
        <serviceName targetNamespace="http://www.extreme.indiana.edu/services/simpleService">SimpleService</serviceName>
        <serviceDescription>A simple service that lists the files in the given directory</serviceDescription>
    </service>
    <portType>
        <method>
            <!-- Method names cannot have special characters like blank spaces in them -->
            <methodName>List</methodName>
            <methodDescription> List files in the given directory </methodDescription>
            <application>
                <applicationName targetNamespace="http://www.extreme.indiana.edu/application/simpleApplication">LS-Application</applicationName>
                <description>This application lists the files in a directory</description>
            </application>
            <inputParameter>
                <parameterName>directoryName</parameterName>
                <parameterType>String</parameterType>
                <parameterDescription>This name of the directory that has to be listed</parameterDescription>
            </inputParameter>
            <outputParameter>
                <parameterName>StandardOut</parameterName>
                <parameterType>StdOut</parameterType>
                <parameterDescription>The standard out of the application</parameterDescription>
            </outputParameter>
        </method>
    </portType>
</ServiceMap>

Supported output parameter types in the ServiceMap document:

• String: A string value
• Integer: An integer value
• Float: A float value
• Double: A double value
• Boolean: A boolean value
• QName: A fully qualified name
• URI: A URI
• StringArray: An unbounded array of strings
• IntegerArray: An unbounded array of integers
• FloatArray: An unbounded array of floats
• DoubleArray: An unbounded array of doubles
• BooleanArray: An unbounded array of boolean values
• URIArray: An unbounded array of URIs
• QNameArray: An array of QNames
  
• LEADFileID: A String that represents a unique identifier for data products produced and consumed by LEAD applications
• LEADFileIDArray: An array of LEADFileIDs
• StdOut: Represents the entire standard out of the application
• StdErr: Represents the entire standard error of the application
  

If the value of the output parameter is a string in the standard out of the application then you must provide a name for the output parameter and a regular expression that will match the value of the output parameter. For example.

<outputParameter>
    <parameterName>OutputParamName</parameterName>
    <parameterType>String</parameterType>
    <parameterDescription>The output result of the application</parameterDescription>
    <regExp>outfile\d[a-zA-Z].*</regExp>
</outputParameter>

In the above example, if the standard out of the application contains a string that matches the specified regular expression, the application service will return the string that matches the regular expression as the output result of the application in the response message to the client/user. The supported data types for output parameters are the same as that for input parameters.

[ << ] [ < ] [ Home ] [ > ] [ >> ]