| <?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> |