Author: chatra
Date: Mon Oct 16 05:07:51 2006
New Revision: 464456
URL: http://svn.apache.org/viewvc?view=rev&rev=464456
Log:
reviewd and committing AXIS2-1405. Thanks Charitha
Modified:
webservices/axis2/branches/java/1_1/modules/samples/xdocs/googleSearch/GoogleSearchHelp.html
Modified:
webservices/axis2/branches/java/1_1/modules/samples/xdocs/googleSearch/GoogleSearchHelp.html
URL:
http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/modules/samples/xdocs/googleSearch/GoogleSearchHelp.html?view=diff&rev=464456&r1=464455&r2=464456
==============================================================================
---
webservices/axis2/branches/java/1_1/modules/samples/xdocs/googleSearch/GoogleSearchHelp.html
(original)
+++
webservices/axis2/branches/java/1_1/modules/samples/xdocs/googleSearch/GoogleSearchHelp.html
Mon Oct 16 05:07:51 2006
@@ -1,126 +1,226 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd";>
-<html>
-<head>
-<title>Untitled Document</title>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-</head>
-
-<body>
- <h1>SOAP base AXIS client for Google Search </h1>
- <h2>Section 1 - Basic Operations</h2>
- <h3><strong>Introduction </strong></h3>
- <p>This is a client that can be used to do Google searches using the
- Google Web API. It allows the user to enter a word as the query parameters in
the given
- text field of the GUI and in a moment is shows the search results in the text
- pane below. The special feature of this client is, when the user presses
the space
- key after typing a word it starts searching for that word and displays the
results while the user typing the next word. This feature is
- made possible by the non blocking invocation capability of Axis2. </p>
- <h3><strong>Getting Started </strong></h3>
- <p>Google search operation is done by means of Google Web API. (You can learn
more and create your own account in Google Web API
- <a href="http://www.google.com/apis/";>here</a>). If you need to build your
own client using this Web API, you should
- obtain a license key which can be obtained easily at the Google Web API page.
</p>
- <p>When you work with this client, you can use the given license key with
this release (This
- default key is included in a property file inside the jar file which will be
- automatically used in the sample when started). However it is convenient for
you to get a license key
- of your own since the daily limit per key is 1000 requests and the limit will
- be reached quickly if a single license key is shared by many users. </p>
- <p>The first and the easiest option is downloading the binary distribution
- which includes the compiled samples. Scripts are included for starting the
- program in either Windows or Unix.</p>
- <p>Second option is to build the samples from source. This has to be done
with
- Maven. All you have to do is go to Modules/Samples and type maven in the
- command prompt. This will compile and will build all the jars required and
copy
- the necessary scripts as well. </p>
- <p>Execute the necessary shell scripts / batch files to start the tool.</p>
- <h3><strong>Items in the UI</strong></h3>
- <p>The following figure shows the UI of the tool</p>
- <p><img border="0" src="sceenShot1.JPG" width="616" height="577"></p>
- <p>The key can be set by using the settings menu</p>
- <p><img border="0" src="screenShot2.JPG" width="163" height="129"></p>
- <p>The Help menu pops up a help window which includes this text</p>
- <p><img border="0" src="screenShot3.JPG" width="193" height="112"></p>
- <p> </p>
- <h3><strong>Operation </strong></h3>
- <p>Now you are ready to do a Google search - SOAP style. Just type the word
you want to search in the small text
- field in the GUI. After you press enter or space, client starts the searching
and you
- will see the results displayed few seconds. </p>
- <p>You can also set the number of results per page from the set menu. Maximum
is 10 results. You can view more results for the last search by pressing More
Results button and can come back to previous page by Previous Page button.
</p>
- <h2>Section 2 - How the sample works </h2>
- <h3><strong>Architecture</strong></h3>
- <p>This client is built from five classes. </p>
- <ol>
- <li>AsynchronousClient:- This class is responsible for sending requests</li>
- <li>ClientUtil:- Utility class to build the soap envelope and the
messageContext; </li>
- <li>ClientCallbackHandler:- receives the response messages and processes it
to extract the required content. </li>
- <li>LinkFollower:- Listens to the hyperlink events and produce new windows
to open relevant URLs.</li>
- <li> GUIHandler:- Builds & shows the GUI, Listens to the events
in the GUI, </li>
- </ol>
- <p><img src="archi.JPG" width="550" height="384"></p>
- <p>The main method is inside the AsynchronousClient class. First it
- instantiates a LinkFollower and a GUIHandler . Then the main program calls to
the GUIHandler to display the GUI. After that, the program
- starts running and captures and acts according to the events fired by the
GUI.
- The KeyListner that listens to the text field events fires a search when it
- detects a space or Enter key . It would not take long time send a request,
but here it's done
- using a separate thread because it's important to isolate the GUI from
internal actions.
- The user never gets interrupted in anyway. So the user can type the query
terms continuously on the
- text field while the program does the search for the query terms that are
already typed and displays the results. </p>
- <p>The use of the other thread comes when the user click on a hyperlink. Then
the program
- pops open the URL in a new window. This may take a while to load up depending
- on the web site. Hence a separate thread is used , where the
LinkFollower
- is made a Thread. </p>
- <h3><strong>More on the Code</strong></h3>
- <p>Now we have two threads, one is for sending the soap request without
interrupting the user and other is to open
- a new windows for clicked URLs. But there is another important action. That
is processing the received response and displaying the results. That is done in
the ClientCallbackHandler. This is
- also an important feature of the InvokeNonBlocking operation of Axis2. It
lets you to have an additional thread in the callbackHandler
- class. All you have to do is send an object of that class as a parameter when
you send the message. How it is done in the
- program is as follows. </p>
- <p><code>call.invokeNonBlocking(opdesc, requestContext, new
ClientEchoCallbackHandler()); </code></p>
- <p>opDesc is a QName which caries the operation name and relevant
namespace. </p>
- <p>requestContext is a MessageContext that holds the request soap envelope.
</p>
- <p>ClientEchoCallbackHandler is a class that receives the response soap
envelope. </p>
- <p>Briefly it is client thread is just sending the requests and is not
waiting for the response. So this client can send any amount of requests
sequentially irrespective of whether the responses are received or not.
ClientEchoCallbackHandler is responsible for receiving response messages and
processing it. It extracts the required details from the message and displays
it in the
- text pane of the GUI. </p>
- <p>The request soap message is built at the ClientUtil class. According to
the Google Web API
- WSDL file, required namespaces are selected and attached to the envelope. We
don't have to include anything in the header. The name of the first child
element of the body should be operation name and it should be namespace
qualified. We also have to include the binding namespace to this element. Here
it is attached as an attribute to that element, </p>
- <p><code>OMElement operation =
omFactory.createOMElement("doGoogleSearch",
"urn:GoogleSearch", "ns1"); </code></p>
- <p><code>opration.addAttribute("SOAP-ENV:encordingStyle",
"http://schemas.xmlsoap.org/soap/encoding/", null); </code></p>
- <p>All the child elements of the operation element are carrying required
parameters such as license key,
- query terms, results per page, etc. (for more information, download the
developer kit from <a
href="http://www.google.com/apis/download.html";>http://www.google.com/apis/download.html
</a>, and refer APIs_Reference.html) </p>
- <p>This is a sample request soap enelope,</p>
- <p><samp><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"><br>
-<soapenv:Header></soapenv:Header><br>
-<soapenv:Body></samp></p>
- <blockquote>
- <p><samp><ns1:doGoogleSearch xmlns:ns1="urn:GoogleSearch"
SOAP-ENV:encordingStyle="http://schemas.xmlsoap.org/soap/encoding/"><br>
-<key xmlns=""
xsi:type="xsd:string">F0wt5EFQFHKxTs+rl3P+27o6D112BTWd</key><br>
-<q xmlns="" xsi:type="xsd:string">axis</q><br>
-<start xmlns=""
xsi:type="xsd:int">0</start><br>
-<maxResults xmlns=""
xsi:type="xsd:int">2</maxResults><br>
-<filter xmlns=""
xsi:type="xsd:boolean">true</filter><br>
-<restrict xmlns=""
xsi:type="xsd:string"></restrict><br>
-<safeSearch xmlns=""
xsi:type="xsd:boolean">false</safeSearch><br>
-<lr xmlns="" xsi:type="xsd:string"></lr><br>
-<ie xmlns=""
xsi:type="xsd:string">latin1</ie><br>
-<oe xmlns=""
xsi:type="xsd:string">latin1</oe><br>
-</ns1:doGoogleSearch></samp></p>
- </blockquote>
- <p><samp></soapenv:Body></soapenv:Envelope></samp></p>
- <p>You can find a sample soap response message from the toolkit that you
download from the Google Web API page.. ClientCallbackHandler
- processing response soap and extract elements which have the local names as
- "snippet" and "URL". It has to work with AXIOM. You can
notice that it uses several Iterators to go through the children of an
OMElement. the Iterator
- returns an object that can be cast into an OMNode. Since you can't call for
the children of an OMNode we have to cast it to an OMElement
- where a type checking needs to be done as follows. </p>
- <p><font face="Courier New"><font size="2">Iterator iterator0 =
operation.getChildren();<br/>
- while (iterator0.hasNext()) { <br/>
- OMNode node = (OMNode) iterator0.next(); <br/>
- if (node.getType() == OMNode.ELEMENT_NODE) { <br/>
- OMElement elem = (OMElement) node;</font> </font> </p>
- <p>A notable fact here is that the text in the snippet element is in the HTML
format. But it cannot be displayed straight away because you have to attach the
HTML header and footer to that. beginHTML and endHTML static variables are
used for that purpose. </p>
- <h3><strong>Extending the Client </strong></h3>
- <p> If you observe the WSDL file of the Google API, you can find two more
operations other than doGoogleSearch. Those are
<strong>"doGetCachedPage"and "
</strong><strong>doSpellingSuggestion" </strong>. You can extend this
program to work these operations too. Because the soap requests and responses
are different, it will need separate ClientUtil classes and
ClientCallbackHandler
- classes to fulfill this task. </p>
- <p> </p>
- <hr/>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<head>
+ <title>Untitled Document</title>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+</head>
+
+<body>
+<h1>SOAP Based AXIS Client for Google Search</h1>
+
+<h2>Section 1 - Basic Operations</h2>
+
+<h3><strong>Introduction</strong></h3>
+
+<p>This is a client that can be used to do Google searches using the Google
+Web API. It allows the user to enter a word as the query parameters in the
+given text field of the GUI and in a moment it shows the search results in
+the text pane below. The special feature of this client is, when the user
+presses the space key after typing a word it starts searching for that word
+and displays the results while the user typing the next word. This feature is
+made possible by the non blocking invocation capability of Axis2. </p>
+
+<h3><strong>Getting Started</strong></h3>
+
+<p>Google search operation is done by means of Google Web API. (You can learn
+more and create your own account in Google Web API <a
+href="http://www.google.com/apis/";>here</a>). If you need to build your own
+client using this Web API, you should obtain a license key which can be
+obtained easily at the Google Web API page.</p>
+
+<p>When you work with this client, you can use the given license key with
+this release (This default key is included in a property file inside the jar
+file which will be automatically used in the sample when started). However it
+is convenient for you to get a license key of your own since the daily limit
+per key is 1000 requests and the limit will be reached quickly if a single
+license key is shared by many users.</p>
+
+<p>The first and the easiest option is downloading the binary distribution
+which includes the compiled samples. Scripts are included for starting the
+program in either Windows or Unix.</p>
+
+<p>Second option is to build the samples from source. This has to be done
+with Maven. All you have to do is go to Modules/Samples and type maven in the
+command prompt. This will compile and will build all the jars required and
+copy the necessary scripts as well.</p>
+
+<p>Execute the necessary shell scripts / batch files to start the tool.</p>
+
+<h3><strong>Items in the UI</strong></h3>
+
+<p>The following figure shows the UI of the tool</p>
+
+<p><img border="0" src="sceenShot1.JPG" width="616" height="577"></p>
+
+<p>The key can be set by using the settings menu</p>
+
+<p><img border="0" src="screenShot2.JPG" width="163" height="129"></p>
+
+<p>The Help menu pops up a help window which includes this text</p>
+
+<p><img border="0" src="screenShot3.JPG" width="193" height="112"></p>
+
+<p> </p>
+
+<h3><strong>Operation</strong></h3>
+
+<p>Now you are ready to do a Google search - SOAP style. Just type the word
+you want to search in the small text field in the GUI. After you press enter
+or space, client starts the searching and you will see the results displayed
+few seconds.</p>
+
+<p>You can also set the number of results per page from the set menu. Maximum
+is 10 results. You can view more results for the last search by pressing
+"More Results" button and can come back to previous page by "Previous Page"
+button.</p>
+
+<h2>Section 2 - How the sample works</h2>
+
+<h3><strong>Architecture</strong></h3>
+
+<p>This client is built from five classes.</p>
+<ol>
+ <li>AsynchronousClient:- This class is responsible for sending requests</li>
+ <li>ClientUtil:- Utility class to build the soap envelope and the
+ messageContext;</li>
+ <li>ClientCallbackHandler:- receives the response messages and processes it
+ to extract the required content.</li>
+ <li>LinkFollower:- Listens to the hyperlink events and produce new windows
+ to open relevant URLs.</li>
+ <li>GUIHandler:- Builds & shows the GUI, Listens to the events in the
+ GUI, </li>
+</ol>
+
+<p><img src="archi.JPG" width="550" height="384"></p>
+
+<p>The main method is inside the AsynchronousClient class. First it
+instantiates a LinkFollower and a GUIHandler . Then the main program calls to
+the GUIHandler to display the GUI. After that, the program starts running and
+captures and acts according to the events fired by the GUI. The KeyListner
+that listens to the text field events fires a search when it detects a space
+or Enter key. It would not take long time send a request, but here it's done
+using a separate thread because it's important to isolate the GUI from
+internal actions. The user never gets interrupted in anyway. So the user can
+type the query terms continuously on the text field while the program does
+the search for the query terms that are already typed and displays the
+results.</p>
+
+<p>The use of the other thread comes when the user click on a hyperlink. Then
+the program opens the URL in a new window. This may take a while to load up
+depending on the web site. Hence a separate thread is used , where the
+LinkFollower is made a Thread. </p>
+
+<h3><strong>More on the Code</strong></h3>
+
+<p>Now we have two threads, one is for sending the soap request without
+interrupting the user and other is to open a new windows for clicked URLs.
+But there is another important action. That is processing the received
+response and displaying the results. That is done in the
+ClientCallbackHandler. This is also an important feature of the
+InvokeNonBlocking operation of Axis2. It lets you to have an additional
+thread in the callbackHandler class. All you have to do is send an object of
+that class as a parameter when you send the message. How it is done in the
+program is as follows. </p>
+
+<p><code>call.invokeNonBlocking(opdesc, requestContext, new
+ClientEchoCallbackHandler());</code></p>
+
+<p>opDesc is a QName which caries the operation name and relevant
+namespace.</p>
+
+<p>requestContext is a MessageContext that holds the request soap
+envelope.</p>
+
+<p>ClientEchoCallbackHandler is a class that receives the response soap
+envelope.</p>
+
+<p>Briefly, client thread is just sending the requests and it is not waiting
+for the response. So this client can send any amount of requests sequentially
+irrespective of whether the responses are received or not.
+ClientEchoCallbackHandler is responsible for receiving response messages and
+processing it. It extracts the required details from the message and displays
+it in the text pane of the GUI.</p>
+
+<p>The request soap message is built at the ClientUtil class. According to
+the Google Web API WSDL file, required namespaces are selected and attached
+to the envelope. We don't have to include anything in the header. The name of
+the first child element of the body should be operation name and it should be
+namespace qualified. We also have to include the binding namespace to this
+element. Here it is attached as an attribute to that element,</p>
+
+<p><code>OMElement operation = omFactory.createOMElement("doGoogleSearch",
+"urn:GoogleSearch", "ns1");</code></p>
+
+<p><code>opration.addAttribute("SOAP-ENV:encordingStyle",
+"http://schemas.xmlsoap.org/soap/encoding/";, null);</code></p>
+
+<p>All the child elements of the operation element are carrying required
+parameters such as license key, query terms, results per page, etc. (for more
+information, download the developer kit from <a
+href="http://www.google.com/apis/download.html";>http://www.google.com/apis/download.html
+</a>, and refer "APIs_Reference.html")</p>
+
+<p>This is a sample request soap enelope,</p>
+
+<p><samp><soapenv:Envelope
+xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/";
+xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/";
+xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance/";
+xmlns:xsd="http://www.w3.org/1999/XMLSchema"><br>
+<soapenv:Header></soapenv:Header><br>
+<soapenv:Body></samp></p>
+
+<blockquote>
+ <p><samp><ns1:doGoogleSearch xmlns:ns1="urn:GoogleSearch"
+ SOAP-ENV:encordingStyle="http://schemas.xmlsoap.org/soap/encoding/"><br>
+ <key xmlns=""
+ xsi:type="xsd:string">F0wt5EFQFHKxTs+rl3P+27o6D112BTWd</key><br>
+ <q xmlns="" xsi:type="xsd:string">axis</q><br>
+ <start xmlns="" xsi:type="xsd:int">0</start><br>
+ <maxResults xmlns="" xsi:type="xsd:int">2</maxResults><br>
+ <filter xmlns="" xsi:type="xsd:boolean">true</filter><br>
+ <restrict xmlns="" xsi:type="xsd:string"></restrict><br>
+ <safeSearch xmlns=""
+ xsi:type="xsd:boolean">false</safeSearch><br>
+ <lr xmlns="" xsi:type="xsd:string"></lr><br>
+ <ie xmlns="" xsi:type="xsd:string">latin1</ie><br>
+ <oe xmlns="" xsi:type="xsd:string">latin1</oe><br>
+ </ns1:doGoogleSearch></samp></p>
+</blockquote>
+
+<p><samp></soapenv:Body></soapenv:Envelope></samp></p>
+
+<p>You can find a sample soap response message from the toolkit that you
+download from the Google Web API page.. ClientCallbackHandler processing
+response soap and extract elements which have the local names as "snippet"
+and "URL". It has to work with AXIOM. You can notice that it uses several
+Iterators to go through the children of an OMElement. the Iterator returns
+an object that can be cast into an OMNode. Since you can't call for the
+children of an OMNode we have to cast it to an OMElement where a type
+checking needs to be done as follows. </p>
+<pre>Iterator iterator0 =
+operation.getChildren();
+while (iterator0.hasNext()) {
+OMNode node = (OMNode) iterator0.next();
+if (node.getType() == OMNode.ELEMENT_NODE) {
+OMElement elem = (OMElement) node;</pre>
+
+<p>A notable fact here is that the text in the snippet element is in the HTML
+format. But it cannot be displayed straight away because you have to attach
+the HTML header and footer to that. "beginHTML" and "endHTML" static
+variables are used for that purpose.</p>
+
+<h3><strong>Extending the Client</strong></h3>
+
+<p>If you observe the WSDL file of the Google API, you can find two more
+operations other than "<strong>doGoogleSearch</strong>". Those are
+<strong>"doGetCachedPage" </strong> and " <strong>doSpellingSuggestion"
+</strong>. You can extend this program to work these operations too. Because
+the soap requests and responses are different, it will need separate
+ClientUtil classes and ClientCallbackHandler classes to fulfill this task.</p>
+
+<p> </p>
+<hr>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
