Author: keith
Date: Sun Jan 27 02:07:39 2008
New Revision: 12993
Log:
Linking to the resty services page from the annotations page
Modified:
trunk/mashup/java/xdocs/annotations.html
Modified: trunk/mashup/java/xdocs/annotations.html
==============================================================================
--- trunk/mashup/java/xdocs/annotations.html (original)
+++ trunk/mashup/java/xdocs/annotations.html Sun Jan 27 02:07:39 2008
@@ -1,131 +1,167 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <meta http-equiv="content-type" content="">
- <title>JavaScript Web Service Annotations</title>
- <link href="styles.css" rel="stylesheet" type="text/css" media="all">
- </head>
+<head>
+
+ <meta http-equiv="content-type" content="">
+ <title>JavaScript Web Service Annotations</title>
+
+
+ <link href="styles.css" rel="stylesheet" type="text/css" media="all">
+
+</head>
+
+
<body>
- <div id="main-content">
- <h1>JavaScript Web Service Annotations</h1>
- <p>
- <strong>Table of Contents</strong>
- </p>
-
- <div class="toc">
- <ul>
- <li><a href="#documentat">documentation Annotation</a></li>
- <li><a href="#visible">visible Annotation</a></li>
- <li><a href="#inputTypes">inputTypes and outputType
Annotations</a></li>
- <li><a href="#Other">Other Annotations</a></li>
- </ul>
- </div>
-
- <p>
- There are a number of annotations that you can insert into
your JavaScript
- Mashup service that enrich the descriptions and tools
generated by the mashup
- service. We encourage you to use these annotations
liberally.
- </p>
-
- <p>
- The WSO2 Mashup Server defines a set of properties that can be
applied to
- the Global object, representing the service as a whole, or to
individual
- functions. In JavaScript, functions are actually
objects, and any object can
- have additional properties dynamically added to it. The set of
common
- properties to set on an object is described below.
- </p>
-
- <h2 id="documentat">documentation Annotation</h2>
-
- <p>
- Documentation properties can be added either to the global
object, or to
- individual function objects.
- </p>
-
- <pre class="Code">this.documentation = <div>The
<b>simple</b> service has a single operation -
<i>echo</i>.</div>; <br/><br/>echo.documentation = "The
echo operation accepts a blob of XML and returns it to the caller
unchanged."<br/><br/>function echo(xmlblob) {<br/> return
xmlblob;<br/>}</pre>
-
- <p>
- The documentation can have either a string value, as shown in
the
- echo.documentation property above, or it can have an XML.
- </p>
-
- <p>The documentation property serves several purposes:</p>
-
- <ol>
- <li>It provides structured documentation within the service.
While you
- could use JavaScript comments instead, using a
documentation property to
- describe the service and its operations makes it possible
to distinguish
- between comments describing the implementation, and
comments documenting
- the behavior of the service, and to re-use the latter.
- </li>
- <li>The documentation for the service (this.documentation)
appears in the
- WSDL as a top-level <documentation> element. The
documentation for
- each operation (echo.documentation in the above example)
appears as
- <documentation> elements on each Interface Operation.
- </li>
- <li>The documentation is displayed in the Try-it page.</li>
- <li>The documentation is also displayed in the ?doc page.</li>
- </ol>
-
- <h2 id="visible">visible Annotation</h2>
-
- <p>
- By default, each function in a JavaScript service file is
exposed as an
- operation. But often functions should be 'private', for
the benefit of other
- functions and not an entry point that the author wishes to
expose to a
- client. When the 'visible' property has the Boolean
value <em>false</em>,
- the function is not exposed as an operation (e.g., it doesn't
appear in the
- WSDL, Try-it, etc.)
- </p>
-
- <pre class="Code">function equals(lefthand,
righthand)<br/>{<br/> return (lefthand == righthand
&& typeEquals(lefthand, righthand));<br/>}<br/><br/>typeEquals.visible
= false;<br/>function typeEquals(lefthand,
righthand)<br/>{<br/> return (typeof(lefthand) ==
typeof(righthand));<br/>}</pre>
-
- <p>
- In the above example, there is an implicit
- "equals.visible = true;".
- </p>
-
- <br/>
-
- <h2 id="inputTypes">inputTypes and outputType Annotations</h2>
- <br/>
- Please refer documentation on <a
- href="dataBinding.html">JavaScript Data Binding</a> for
details.<br/>
- <br/>
- <h2 id="Other">Other Annotations</h2>
-
- <p>For advanced usage, there are a number of other properties that
can be used:</p>
-
- <ul>
- <li><b>this.targetNamespace </b>: places the components of the
description
- (WSDL 2.0, WSDL 1.1) in a specific namespace. By
default, the
- targetNamespace is <a
href="http://services.mashup.wso2.org/%7bservice%20name%7d";>http://services.mashup.wso2.org/{service
- name}</a>, which is of course not guaranteed to be unique.
- </li>
- <li><b>this.schemaTargetNamespace</b> : sets the schema target
namespace,
- which will be used as the namespace for any wrapper
elements generated by
- the mashup server. By default the targetnamespace is
<a
-
href="http://services.mashup.wso2.org/%7bservice%20name%7d?xsd";>http://services.mashup.wso2.org/{service
- name}?xsd</a>.
- </li>
- <li><b>this.serviceName</b> : exposes the service under an
alternate name
- (in the WSDL, try-it, documentation, etc.) By
default the serviceName is
- the name of the JavaScript file (minus the '.js'.)
- </li>
- <li><b>{function}.safe</b> :indicates whether repeated calls
to the
- operation cause side effects. For example, two calls
to a 'bill me'
- operation would normally result in two charges, while two
calls to a
- 'current activity' operation would not cause any harmful
side-effects.
- The safe annotation maps to the wsdlx:safe attribute, and
helps determine
- whether GET or POST is the most appropriate HTTP method to
use.
- </li>
- <li><b>{function}.operationName</b> : exposes the function as
an operation
- under an alternate name (in the WSDL, try-it,
documentation, etc.). By
- default, the operationName is the name of the function.
- </li>
- </ul>
- <p>© WSO2 Inc.</p>
- </div>
- </body>
-</html>
\ No newline at end of file
+<div id="main-content">
+<h1>JavaScript Web Service Annotations</h1>
+
+<p> <strong>Table of Contents</strong> </p>
+
+<div class="toc">
+<ul>
+
+ <li><a href="#documentat">documentation Annotation</a></li>
+
+ <li><a href="#visible">visible Annotation</a></li>
+
+ <li><a href="#inputTypes">inputTypes and
+outputType Annotations</a></li>
+
+ <li><a href="#httpMethod">httpMethod and httpLocation Annotations</a></li>
+
+
+ <li><a href="#Other">Other Annotations</a></li>
+
+</ul>
+
+</div>
+
+<p> There are a number of annotations that you can insert into
+your JavaScript Mashup service that enrich the descriptions and tools
+generated by the mashup service. We encourage you to use
+these annotations liberally. </p>
+
+<p> The WSO2 Mashup Server defines a set of properties that can
+be applied to the Global object, representing the service as a whole,
+or to individual functions. In JavaScript, functions are
+actually objects, and any object can have additional properties
+dynamically added to it. The set of common properties to set on an
+object is described below.</p>
+
+<p>There are two groups of annotations. Some annotations are used
+at service level while the others are used at an operation level. The
+documentation annotaion is used at both service and operation level. </p>
+
+<h2 id="documentat">documentation Annotation </h2>
+
+<p> Documentation properties can be added either to the global
+object, or to individual function objects. </p>
+
+<pre class="Code">this.documentation = <div>The
<b>simple</b> service has a single operation -
<i>echo</i>.</div>; <br><br>echo.documentation = "The
echo operation accepts a blob of XML and returns it to the caller
unchanged."<br><br>function echo(xmlblob) {<br> return xmlblob;<br>}</pre>
+
+<p> The documentation can have either a string value, as shown in
+the echo.documentation property above, or it can have an XML. </p>
+
+<p>The documentation property serves several purposes:</p>
+
+<ol>
+
+ <li>It provides structured documentation within the service.
+While you could use JavaScript comments instead, using a documentation
+property to describe the service and its operations makes it possible
+to distinguish between comments describing the implementation, and
+comments documenting the behavior of the service, and to re-use the
+latter. </li>
+
+ <li>The documentation for the service (this.documentation)
+appears in the WSDL as a top-level <documentation>
+element. The documentation for each operation (echo.documentation in
+the above example) appears as <documentation> elements on
+each Interface Operation. </li>
+
+ <li>The documentation is displayed in the Try-it page.</li>
+
+ <li>The documentation is also displayed in the ?doc page.</li>
+
+</ol>
+
+<h2 id="visible">visible Annotation</h2>
+
+<p> By default, each function in a JavaScript service file is
+exposed as an operation. But often functions should be
+'private', for the benefit of other functions and not an entry point
+that the author wishes to expose to a client. When the
+'visible' property has the Boolean value <em>false</em>,
+the function is not exposed as an operation (e.g., it doesn't appear in
+the WSDL, Try-it, etc.) </p>
+
+<pre class="Code">function equals(lefthand,
righthand)<br>{<br> return (lefthand == righthand &&
typeEquals(lefthand, righthand));<br>}<br><br>typeEquals.visible =
false;<br>function typeEquals(lefthand, righthand)<br>{<br>
return (typeof(lefthand) == typeof(righthand));<br>}</pre>
+
+<p> In the above example, there is an implicit "equals.visible =
+true;". </p>
+
+<br>
+
+<h2 id="inputTypes">inputTypes and outputType Annotations</h2>
+
+<br>
+
+Please refer documentation on <a href="dataBinding.html">JavaScript
+Data Binding</a> for details.<br>
+
+<br>
+
+<h2 id="httpMethod">httpMethod and httpLocation Annotations</h2>
+
+<br>
+
+Please refer documentation on <a href="restyservices.html">Writing
+RESTy Services</a> for details.<br>
+
+<br>
+
+<h2 id="Other">Other Annotations</h2>
+
+<p>For advanced usage, there are a number of other properties
+that can be used:</p>
+
+<ul>
+
+ <li><b>this.targetNamespace </b>: places the
+components of the description (WSDL 2.0, WSDL 1.1) in a specific
+namespace. By default, the targetNamespace is <a
href="http://services.mashup.wso2.org/%7bservice%20name%7d";>http://services.mashup.wso2.org/{service
+name}</a>, which is of course not guaranteed to be unique. </li>
+
+ <li><b>this.schemaTargetNamespace</b> : sets the
+schema target namespace, which will be used as the namespace for any
+wrapper elements generated by the mashup server. By default
+the targetnamespace is <a
href="http://services.mashup.wso2.org/%7bservice%20name%7d?xsd";>http://services.mashup.wso2.org/{service
+name}?xsd</a>. </li>
+
+ <li><b>this.serviceName</b> : exposes the service
+under an alternate name (in the WSDL, try-it, documentation,
+etc.) By default the serviceName is the name of the
+JavaScript file (minus the '.js'.) </li>
+
+ <li><b>{function}.safe</b> :indicates whether
+repeated calls to the operation cause side effects. For
+example, two calls to a 'bill me' operation would normally result in
+two charges, while two calls to a 'current activity' operation would
+not cause any harmful side-effects. The safe annotation maps
+to the wsdlx:safe attribute, and helps determine whether GET or POST is
+the most appropriate HTTP method to use. </li>
+
+ <li><b>{function}.operationName</b> : exposes the
+function as an operation under an alternate name (in the WSDL, try-it,
+documentation, etc.). By default, the operationName is the
+name of the function. </li>
+
+</ul>
+
+<p>� WSO2 Inc.</p>
+
+</div>
+
+</body>
+</html>
_______________________________________________
Mashup-dev mailing list
[email protected]
http://www.wso2.org/cgi-bin/mailman/listinfo/mashup-dev
