1_5/modules/samples/servicelifecycle/doc/servicelifecycleguide.html - axis-axis2-java-core - Git at Google

 <?xml version="1.0" encoding="iso-8859-1"?>

 <!--
   ~ Licensed to the Apache Software Foundation (ASF) under one
   ~ or more contributor license agreements. See the NOTICE file
   ~ distributed with this work for additional information
   ~ regarding copyright ownership. The ASF licenses this file
   ~ to you under the Apache License, Version 2.0 (the
   ~ "License"); you may not use this file except in compliance
   ~ with the License. You may obtain a copy of the License at
   ~
   ~ http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Unless required by applicable law or agreed to in writing,
   ~ software distributed under the License is distributed on an
   ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   ~ KIND, either express or implied. See the License for the
   ~ specific language governing permissions and limitations
   ~ under the License.
   -->

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
   <title>Service Life Cycle Sample Guide</title>
   <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
   />
 </head>

 <body>
 <h1>Service Life Cycle Sample Guide</h1>

 <h2>Introduction</h2>

 <p>This sample is to demonstrate usage of a service life cycle interface and
 session scoping with a sample on application scope session. The sample
 consists of two parts, Service and Client.</p>

 <p>Let's take a library system, which has the following operations, as the
 scenario for this sample.</p>
 <ul>
   <li>Register user</li>
   <li>Login to system</li>
   <li>View all books</li>
   <li>View available books</li>
   <li>View lend books</li>
   <li>Lend and return books</li>
 </ul>

 <h2>Why Do We Need Service Life Cycle Here?</h2>

 <p>In order to make sure that at the runtime service impl class can access
 data read from anywhere, we need to initialize the service at deployment.
 Let's forget about the session for a minute and think about the scenario
 where you want to populate a bean or need to start a Data Base connection for
 the service. In such a situation having service life cycle class is very
 useful.</p>

 <p>In this sample you will learn how to use the service life cycle class for
 your application. The interface has only two methods</p>
 <ol>
   <li>startUp</li>
   <li>shutDown</li>
 </ol>

 <p>Where startUp method will be called when the service is deployed and it
 will call only once for that particular service, while shutDown method calls
 when system shutdown.</p>

 <p>So in this sample, the life cycle class will load the library inside the
 startUp method. At the very first time the system will load from
 services.xml. It has all the available books in the system. And at the time
 of system shutdown it will save the status of the library into a file
 (library.xml) in the java.io.temp directory. So the next time onwards it will
 populate library using the above file. So all the changes will be there in
 the new instance as well.</p>

 <h2>Prerequisites</h2>

 <p>You will have to install <a href="http://ant.apache.org/">Apache Ant</a>
 1.6.2 or later.</p>

 <h2>Running the Sample</h2>

 <h3>How to Build the Service?</h3>

 <p>Building the service is just a matter of running ant build file. It will
 create the service aar file, or you could just run the copy.to.tomcat goal
 which will copy the aar file into tomcat/web-app/axis2/WEB-INF/services
 directory.</p>

 <p>Next, go to http://[url and port to your app server]/axis2 and see whether
 your service is listed there.</p>

 <h3>How to Invoke the Service</h3>

 <p>You can invoke complete service using REST API, but it only works in
 application servers like Apache Tomcat and it will not work in
 SimpleHttpServer. First try to use library system using REST API.</p>

 <p>This sample is a simple one and will not do complex tasks. So let's follow
 steps given below to make sure that the sample works as it should:</p>

 <p><strong>Step 1</strong>:- View all the available books in the library,
 just type the URL
 http://127.0.0.1:8080/axis2/services/Library/listAvailableBook on your
 favorite browser.</p>

 <p>You will see all the available books in the system.</p>

 <p><strong>Step 2</strong> : View all the books in the system at
 http://127.0.0.1:8080/axis2/services/Library/listAllBook</p>

 <p>In this case you will get exactly the same result for both the request,
 since no one has borrowed the book.</p>

 <p><strong>Step 3</strong>: Now look at all the lent books in the system. And
 you will see an empty list at
 http://127.0.0.1:8080/axis2/services/Library/listLendBook</p>

 <p><strong>Step 4</strong> : Register a user. To lend a book or return a
 book, you need to register first. Do not register twice, if you try to do so
 you will get an exception.</p>

 <p>To register you need to give user name and password (have a look at the
 wsdl at http://127.0.0.1:port/axis2/services/serviceName?wsdl. You will see
 what you need to pass in)</p>

 <p>So let's create a user called 'foo' with the password '123'
 (http://127.0.0.1:8080/axis2/services/Library/register?userName=foo&amp;passWord=123)</p>

 <p>Then you will get the following response, if everything has gone well.</p>
 <pre>&lt;ns:registerResponse&gt;
 &lt;ns:return&gt;true&lt;/ns:return&gt;
 &lt;/ns:registerResponse&gt;</pre>

 <p><strong>Step 5</strong> : Log into system. To log in you need to pass user
 name and password. So let's try to login to system. The request will be
 http://127.0.0.1:8080/axis2/services/Library/login?userName=foo&amp;passWord=123</p>

 <p><strong>Step 6</strong> : Now we are ready to lend a book. To lend a book
 you need to pass isbn and userName. Let's try to lend the book with isbn
 0-937175-77-3, your request would look like below:</p>

 <p>http://127.0.0.1:8080/axis2/services/Library/lendBook?isbn=0-937175-77-3&amp;userName=foo</p>

 <p>If everything went well, you will see the following response in the
 browser.</p>
 <pre>&lt;ns:lendBookResponse&gt;
 &lt;ns:return&gt;
 &lt;author&gt;John Bloomer&lt;/author&gt;
 &lt;isbn&gt;0-937175-77-3&lt;/isbn&gt;
 &lt;title&gt;Power Programming with RPC&lt;/title&gt;
 &lt;/ns:return&gt;
 &lt;/ns:lendBookResponse&gt;</pre>

 <p><strong>Step 7</strong> : Now go and look at lent list again at
 http://127.0.0.1:8080/axis2/services/Library/listLendBook, you will see the
 following output in the browser.</p>
 <pre>&lt;ns:listLendBookResponse&gt;
 &lt;ns:return&gt;
 &lt;author&gt;John Bloomer&lt;/author&gt;
 &lt;isbn&gt;0-937175-77-3&lt;/isbn&gt;
 &lt;title&gt;Power Programming with RPC&lt;/title&gt;
 &lt;/ns:return&gt;
 &lt;/ns:listLendBookResponse&gt;</pre>

 <p>That's the book you just lent!</p>

 <p>Note : Now if we view the available books, you will not see the above book
 in that list.</p>

 <p><strong>Step 8</strong> : Now let's return the book.</p>

 <p>http://127.0.0.1:8080/axis2/services/Library/returnBook?isbn=
 0-937175-77-3</p>

 <p><strong>Step 9</strong> : Now let's look at the lent book list again, and
 you will realize that list is empty.</p>

 <p><strong>Step 10</strong> : Lend few more book and re-start the app server
 (say Tomcat), and see whether all the previous data is there in the new
 instance.</p>

 <h3>Running the Java Client</h3>

 <p>Open up the LibraryServiceClient java class in your favorite IDE and run
 the main class. And you can comment out the methods you do not wish to invoke
 while un-commenting the method(s) you want to invoke.</p>

 <p>Java client also can be run using <a
 href="http://ant.apache.org/">Ant</a>. You can execute the client and invoke
 service typing <code>ant run.client</code> command in the
 Axis2_HOME/samples/servicelifecycle</p>

 <p>And then follow the instructions as mentioned in the console.</p>
 </body>
 </html>
	<?xml version="1.0" encoding="iso-8859-1"?>

	<!--
	~ Licensed to the Apache Software Foundation (ASF) under one
	~ or more contributor license agreements. See the NOTICE file
	~ distributed with this work for additional information
	~ regarding copyright ownership. The ASF licenses this file
	~ to you under the Apache License, Version 2.0 (the
	~ "License"); you may not use this file except in compliance
	~ with the License. You may obtain a copy of the License at
	~
	~ http://www.apache.org/licenses/LICENSE-2.0
	~
	~ Unless required by applicable law or agreed to in writing,
	~ software distributed under the License is distributed on an
	~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	~ KIND, either express or implied. See the License for the
	~ specific language governing permissions and limitations
	~ under the License.
	-->

	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
	<title>Service Life Cycle Sample Guide</title>
	<meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
	/>
	</head>

	<body>
	<h1>Service Life Cycle Sample Guide</h1>

	<h2>Introduction</h2>

	<p>This sample is to demonstrate usage of a service life cycle interface and
	session scoping with a sample on application scope session. The sample
	consists of two parts, Service and Client.</p>

	<p>Let's take a library system, which has the following operations, as the
	scenario for this sample.</p>
	<ul>
	<li>Register user</li>
	<li>Login to system</li>
	<li>View all books</li>
	<li>View available books</li>
	<li>View lend books</li>
	<li>Lend and return books</li>
	</ul>

	<h2>Why Do We Need Service Life Cycle Here?</h2>

	<p>In order to make sure that at the runtime service impl class can access
	data read from anywhere, we need to initialize the service at deployment.
	Let's forget about the session for a minute and think about the scenario
	where you want to populate a bean or need to start a Data Base connection for
	the service. In such a situation having service life cycle class is very
	useful.</p>

	<p>In this sample you will learn how to use the service life cycle class for
	your application. The interface has only two methods</p>
	<ol>
	<li>startUp</li>
	<li>shutDown</li>
	</ol>

	<p>Where startUp method will be called when the service is deployed and it
	will call only once for that particular service, while shutDown method calls
	when system shutdown.</p>

	<p>So in this sample, the life cycle class will load the library inside the
	startUp method. At the very first time the system will load from
	services.xml. It has all the available books in the system. And at the time
	of system shutdown it will save the status of the library into a file
	(library.xml) in the java.io.temp directory. So the next time onwards it will
	populate library using the above file. So all the changes will be there in
	the new instance as well.</p>

	<h2>Prerequisites</h2>

	<p>You will have to install <a href="http://ant.apache.org/">Apache Ant</a>
	1.6.2 or later.</p>

	<h2>Running the Sample</h2>

	<h3>How to Build the Service?</h3>

	<p>Building the service is just a matter of running ant build file. It will
	create the service aar file, or you could just run the copy.to.tomcat goal
	which will copy the aar file into tomcat/web-app/axis2/WEB-INF/services
	directory.</p>

	<p>Next, go to http://[url and port to your app server]/axis2 and see whether
	your service is listed there.</p>

	<h3>How to Invoke the Service</h3>

	<p>You can invoke complete service using REST API, but it only works in
	application servers like Apache Tomcat and it will not work in
	SimpleHttpServer. First try to use library system using REST API.</p>

	<p>This sample is a simple one and will not do complex tasks. So let's follow
	steps given below to make sure that the sample works as it should:</p>

	<p><strong>Step 1</strong>:- View all the available books in the library,
	just type the URL
	http://127.0.0.1:8080/axis2/services/Library/listAvailableBook on your
	favorite browser.</p>

	<p>You will see all the available books in the system.</p>

	<p><strong>Step 2</strong> : View all the books in the system at
	http://127.0.0.1:8080/axis2/services/Library/listAllBook</p>

	<p>In this case you will get exactly the same result for both the request,
	since no one has borrowed the book.</p>

	<p><strong>Step 3</strong>: Now look at all the lent books in the system. And
	you will see an empty list at
	http://127.0.0.1:8080/axis2/services/Library/listLendBook</p>

	<p><strong>Step 4</strong> : Register a user. To lend a book or return a
	book, you need to register first. Do not register twice, if you try to do so
	you will get an exception.</p>

	<p>To register you need to give user name and password (have a look at the
	wsdl at http://127.0.0.1:port/axis2/services/serviceName?wsdl. You will see
	what you need to pass in)</p>

	<p>So let's create a user called 'foo' with the password '123'
	(http://127.0.0.1:8080/axis2/services/Library/register?userName=foo&passWord=123)</p>

	<p>Then you will get the following response, if everything has gone well.</p>
	<pre><ns:registerResponse>
	<ns:return>true</ns:return>
	</ns:registerResponse></pre>

	<p><strong>Step 5</strong> : Log into system. To log in you need to pass user
	name and password. So let's try to login to system. The request will be
	http://127.0.0.1:8080/axis2/services/Library/login?userName=foo&passWord=123</p>

	<p><strong>Step 6</strong> : Now we are ready to lend a book. To lend a book
	you need to pass isbn and userName. Let's try to lend the book with isbn
	0-937175-77-3, your request would look like below:</p>

	<p>http://127.0.0.1:8080/axis2/services/Library/lendBook?isbn=0-937175-77-3&userName=foo</p>

	<p>If everything went well, you will see the following response in the
	browser.</p>
	<pre><ns:lendBookResponse>
	<ns:return>
	<author>John Bloomer</author>
	<isbn>0-937175-77-3</isbn>
	<title>Power Programming with RPC</title>
	</ns:return>
	</ns:lendBookResponse></pre>

	<p><strong>Step 7</strong> : Now go and look at lent list again at
	http://127.0.0.1:8080/axis2/services/Library/listLendBook, you will see the
	following output in the browser.</p>
	<pre><ns:listLendBookResponse>
	<ns:return>
	<author>John Bloomer</author>
	<isbn>0-937175-77-3</isbn>
	<title>Power Programming with RPC</title>
	</ns:return>
	</ns:listLendBookResponse></pre>

	<p>That's the book you just lent!</p>

	<p>Note : Now if we view the available books, you will not see the above book
	in that list.</p>

	<p><strong>Step 8</strong> : Now let's return the book.</p>

	<p>http://127.0.0.1:8080/axis2/services/Library/returnBook?isbn=
	0-937175-77-3</p>

	<p><strong>Step 9</strong> : Now let's look at the lent book list again, and
	you will realize that list is empty.</p>

	<p><strong>Step 10</strong> : Lend few more book and re-start the app server
	(say Tomcat), and see whether all the previous data is there in the new
	instance.</p>

	<h3>Running the Java Client</h3>

	<p>Open up the LibraryServiceClient java class in your favorite IDE and run
	the main class. And you can comment out the methods you do not wish to invoke
	while un-commenting the method(s) you want to invoke.</p>

	<p>Java client also can be run using <a
	href="http://ant.apache.org/">Ant</a>. You can execute the client and invoke
	service typing <code>ant run.client</code> command in the
	Axis2_HOME/samples/servicelifecycle</p>

	<p>And then follow the instructions as mentioned in the console.</p>
	</body>
	</html>