Author: keith
Date: Sat Jan 26 23:17:26 2008
New Revision: 12982
Log:
Changing eprs to reflect authorname/serviceName and adding details of _private
dir
Modified:
trunk/mashup/java/xdocs/generatedresources.html
Modified: trunk/mashup/java/xdocs/generatedresources.html
==============================================================================
--- trunk/mashup/java/xdocs/generatedresources.html (original)
+++ trunk/mashup/java/xdocs/generatedresources.html Sat Jan 26 23:17:26 2008
@@ -1,85 +1,193 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
- <meta http-equiv="content-type" content="">
- <title>Automatically Generated Resources</title>
- <link href="styles.css" rel="stylesheet" type="text/css" media="all">
+
+
+
+
+ <meta http-equiv="content-type" content="">
+
+
+
+
+
+
+ <title>Automatically Generated Resources</title>
+ <link href="styles.css" rel="stylesheet" type="text/css" media="all">
</head>
-<body>
+<body>
+<h2> Automatically Generated Resources
+</h2>
<div id="main-content">
-<h1>Automatically Generated Resources</h1>
<p></p>
+
+
<p><strong>Table of Contents</strong></p>
+
+
<div class="toc">
- <ul>
+
+<ul>
+
+
<li><a href="#WSDL">WSDL (?wsdl2, ?wsdl)</a></li>
+
+
<li><a href="#Schema">XML Schema (?xsd)</a></li>
+
+
<li><a href="#JavaScript">JavaScript Stubs (?stub)</a></li>
+
+
<li><a href="#Try-it">Try-it (?tryit)</a></li>
+
+
<li><a href="#Documentat">API Documentation (?doc)</a></li>
+
+
<li><a href="#Source">Source Code (?source)</a></li>
- </ul>
+
+
+
+</ul>
+
+
</div>
-<p>Just by virtue of deploying the service, the WSO2 mashup server generates
- a number of descriptive artifacts and tools to make it easy to consume the
- web service you've just created. These artifacts are linked from the
- management console for the service, or can be accessed directly from the
+
+
+
+
+<p>Just by virtue of deploying the service, the WSO2 mashup
+ server generates
+ a number of descriptive artifacts and tools to make it easy to consume
+ the
+ web service you've just created. These artifacts are linked from the
mashup page which can be accessed via the
+ management console, or can be accessed directly from
+ the
endpoint URI associated with the service. Typically the endpoint URI is
- http://{host ip}:7762/services/{service name}, where the service name is by
+ http://{host ip}:7762/services/{username of author}/{service name}, where
the service name
+ is by
default the name of the JavaScript file defining the service (minus the
'.js'). By appending one of the following queries to the endpoint URI,
different artifacts and tools can be accessed:</p>
-<p></p>
-<table class="MsoTableGrid" border="1" cellspacing="0" cellpadding="5"
- style="margin-left:.5in;border-collapse:collapse;">
+
+<table class="MsoTableGrid" style="margin-left: 0.5in; border-collapse:
collapse;" border="1" cellpadding="5" cellspacing="0">
+
+
<caption></caption>
<tbody>
+
+
<tr>
+
+
<td>?wsdl2</td>
+
+
<td>WSDL 2.0 description of the service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?wsdl</td>
+
+
<td>WSDL 1.1 description of the service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?xsd</td>
+
+
<td>XML Schema description of the service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?stub</td>
+
+
<td>JavaScript or E4X stub for accessing the service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?tryit</td>
+
+
<td>Ajax client for simple, generic interactions with the
service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?source</td>
+
+
<td>The JavaScript source code for the service</td>
+
+
</tr>
+
+
<tr>
+
+
<td>?doc</td>
+
+
<td>Documentation for the service</td>
+
+
</tr>
- </tbody>
+
+
+
+
+ </tbody>
</table>
+
+
<p></p>
+
+
<h2 id="WSDL">WSDL (?wsdl2, ?wsdl)</h2>
+
+
<p>By appending '?wsdl2' to the endpoint URI, you can retrieve an
automatically-generated WSDL 2.0 document describing the service. For the
- helloworld service, try <a
-
href="http://localhost:9762/service/helloworld?wsdl2";>http://localhost:7762/service/helloworld?wsdl2</a>.
+ helloworld service, try <a
href="http://localhost:9762/service/helloworld?wsdl2";>http://localhost:7762/service/bob/helloworld?wsdl2</a>
(Assuming bob is the author of helloworld).
The WSDL describes the operations the service exposes, the structure of the
XML that is sent and received by each operation, and how to communicate
with
the service to retrieve the XML content. By default, six different types of
@@ -87,163 +195,230 @@
WSDL 2.0 <endpoint> elements of the service, and by the
<binding>
elements which these endpoints refer to. The default six types of endpoints
are:</p>
+
+
<ol>
+
+
<li>SOAP 1.2 over HTTP</li>
+
+
<li>SOAP 1.1 over HTTP</li>
- <li>Plain old XML over HTTP</li>
+
+
+ <li>Plain old XML/REST over HTTP</li>
+
+
<li>SOAP 1.2 over HTTPS</li>
+
+
<li>SOAP 1.1 over HTTPS</li>
- <li>Plain old XML over HTTPS</li>
+
+
+ <li>Plain old XML/REST over HTTPS</li>
+
+
</ol>
+
+
<p>One can also get a WSDL 1.1 description of the service by appending
- '?wsdl' to the endpoint URI. For the helloworld service, try <a
-
href="http://localhost:9762/service/helloworld?wsdl";>http://localhost:7762/service/helloworld?wsdl</a>.
+ '?wsdl' to the endpoint URI. For the helloworld service, try <a
href="http://localhost:9762/service/helloworld?wsdl";>http://localhost:7762/service/bob/helloworld?wsdl</a>.
</p>
+
+
<p>For more information on precisely how the Mashup Server generates WSDL,
see <a href="annotations.html">JavaScript Annotations</a>.</p>
+
+
<h2 id="Schema">XML Schema (?xsd)</h2>
+
+
<p>Although accessing '?wsdl' or '?wsdl2' gives you a service description
that includes an XML Schema description of the XML structure, you can also
ask for the XML Schema separately using the '?xsd' option. For the
- helloworld service, try <a
-
href="http://localhost:9762/services/helloworld?xsd";>http://localhost:7762/services/helloworld?xsd</a>.
+ helloworld service, try <a
href="http://localhost:9762/services/helloworld?xsd";>http://localhost:7762/services/bob/helloworld?xsd</a>.
</p>
+
+
<h2 id="JavaScript">JavaScript Stubs (?stub)</h2>
+
+
<p>Most Web Service toolkits can successfully use the WSDL description to
provide a nice programming model for accessing the service. For instance,
WSO2 Web Services Application Server (WSAS) provides a utility wsdl2java
which generates Java code for interacting with the service in a manner
friendly to Java programmers.</p>
+
+
<p>Similarly, the Mashup Server provides a tool for interacting with a
service in a manner friendly to JavaScript programmers. The '?stub' option
returns a JavaScript file that can be included in a Web page or another
mashup service to make interacting with the service easy and natural. For
example, if a web page is to interact with the hello world service, you
only
have to include the stub and you can use the WSRequest object -- available
- natively in the Mashup Server, or in the browser through an ActiveX control
- (IE), XPI plugin (Firefox), or a simple version in native JavaScript (shown
+ natively in the Mashup Server, or a simple version in native JavaScript
(shown
below) -- to call the Web service simply and naturally.</p>
+
+
<p></p>
-<pre class="Code"><script type="text/javascript"
src="/js/wso2/WSRequest.js"></script>
-<script type="text/javascript"
src="/services/helloworld?stub"></script>
-<script type="text/javascript">
- function callhelloworld() {
- try {
- helloworldReturn = helloworld.hello();
- } catch (e) {
- alert(e)
- }
- // do this in IE
- alert(helloworldReturn.documentElement.xml);
-
-// Firefox-specific way to serialize XML
- alert(helloworldReturn.documentElement.textContent);
- }
-</script>
+<pre class="Code"><html><br> <head><br>
<title>Simple Client for the helloworld service</title><br>
<script type="text/javascript"
src="/js/wso2/WSRequest.js"></script><br> <script
type="text/javascript"
src="/services/bob/helloworld?stub"></script><br> <br>
<script type="text/javascript"><br> <br> function
callhelloworld() {<br> try {<br>
helloworldReturn = helloworld.hello();<br> } catch (e) {<br>
alert(e)<br> }<br>
alert(helloworldReturn);<br> }<br> </script><br>
</head><br> <body><br> <input type="button" value="say
hello" onclick="callhelloworld()"></input><br>
</body><br></html><br></pre>
-....
-<input type="button" value="say hello"
onclick="callhelloworld()"></input>
-</pre>
<p></p>
+
+
<p>The '?stub' option further more accepts additional parameters:</p>
+
+
<ul>
+
+
<li><b>lang</b>: Whether the stub should use native E4X XML datatypes, or
use DOM to represent XML. The value 'e4x' indicates that native E4X
datatypes should be used, the values 'js', 'ecmascript', and
'javascript'
are synonymous terms for indicating that XML should be exposed through
the DOM.
</li>
+
+
<li><b>service</b>: When a WSDL 2.0 document from which the stub is
generated contains more than one <service> element, this
parameter
can be used to select which service to build a stub for. By default the
first <service> is used. When writing services in JavaScript,
each
- file corresponds to a single service.
- </li>
+ file corresponds to a single service.</li>
+
+ <li><span style="font-weight: bold;">localhost</span>: When set to
+true returns a stub that has the endpoint reference as localhost
+instead of using an IP. Optimum for a Mashup hosted on this server
+(especially for including).</li>
+
+
</ul>
+
+
<p>For more information on using stubs, especially on using them
asynchronously, see <a href="consumingservices.html">Using Stubs</a>.</p>
+
+
<p></p>
+
+
<h2 id="Try-it">Try-it (?tryit)</h2>
+
+
<p>The first thing you might want to do with your new service is try it out.
The '?tryit' option provides a quick and easy way to exercise the service
right out of the box. The try-it window for a service might look something
like this:</p>
+
+
<p><img src="images/storexml_tryit.png" title="Try the Service"></p>
+
+
<p>You can choose the operation you'd like to invoke from the list on the
left hand side, fill in the necessary parameters, and invoke the operation
to
view the result. If you need more typing space (for instance, the parameter
takes a blob of XML) you can expand the size of the input field by clicking
on the small icon in the lower right corner of each field.</p>
+
+
<p>A few notes about the Try-it page:</p>
+
+
<ul>
+
+
<li>The documentation from the documentation annotation is displayed, and
good documentation makes the try-it much nicer to use. I hope this
- encourages you to use the available documentation facilities!
- </li>
+ encourages you to use the available documentation facilities!</li>
+
+
<li>The input fields for the parameters initially show the XML Schema type
of data that's expected. 'anyType' means an XML element. Note that you
are responsible for keeping the XML for these types of services
well-formed. You can also get this information from the tooltip.
</li>
+
+
<li>The try-it page is a full Ajax client and interacts with the service
just as any other client would, so it's a good way to verify that a
service not only works, but is reachable by the clients.
</li>
+
+
<li>The try-it page can dynamically switch between the available endpoints
- using the Choose endpoint list. You can choose an appropriate endpoint,
+ using the expand to change link. You can choose an appropriate
endpoint,
manually edit the endpoint address if necessary (e.g., to redirect
messages through <a
href="http://ws.apache.org/commons/tcpmon";>tcpmon</a>),
and if appropriate link to an alternate try-it that makes more
endpoints available (when the try-it page is served up under HTTP, only
HTTP endpoints appear, but if you get the try-it page from HTTPS, then
- HTTPS endpoints may appear instead.)
+ HTTPS endpoints may appear instead.). The current endpoint is used is
displyed on the top left corner of the page.
</li>
+
+
<li>The try-it page is fully asynchronous, so it doesn't block while a Web
service is being invoked. You could invoke several operations before
one
of them completes (though it doesn't have a way to see the results of
the
same operation invoked multiple times.)
</li>
+
+
</ul>
+
+
<p>Feel free to take the Try-it as the basis for a custom Ajax-style Web
application to interact with your service. You'll find the source code
quite
minimal.</p>
+
+
<h2 id="Documentat">API Documentation (?doc)</h2>
-<p>The documentation for a service, as defined in by the <a
- href="annotations.html#documentat">'documentation' annotations</a>,
can be
+
+
+<p>The documentation for a service, as defined in by the <a
href="annotations.html#documentat">'documentation' annotations</a>, can be
accessed with the '?doc' query. The returned HTML format is intended for
reference,
printout, etc.</p>
+
+
<h2 id="Source">Source Code (?source)</h2>
+
+
<p>The source code for a service can be accessed through the '?source'
option. By default, the source code is available for each service, but in
a future release, we will allow you to prevent others from viewing,
copying,
adapting, or even fixing your code with an option in the administrative
console.</p>
+
+
</div>
-<p>© WSO2 Inc.</p>
+
+
+<p>� WSO2 Inc.</p>
+
+
</body>
</html>
_______________________________________________
Mashup-dev mailing list
[email protected]
http://www.wso2.org/cgi-bin/mailman/listinfo/mashup-dev
