| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
| <html> | |
| <head><link rel="stylesheet" href="../../../print.css" type="text/css" media="print"> | |
| <title>Getting Started with RESTful Web Services - NetBeans IDE Tutorial</title> | |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> | |
| <meta name="KEYWORDS" content="NETBEANS, TUTORIAL, GUIDE, USER, DOCUMENTATION, WEB SERVICE, WEB SERVICES, REST, RESTFUL"> | |
| <meta name="description" | |
| content="This tutorial shows how to use NetBeans IDE | |
| to work with RESTful web services."> | |
| <link rel="stylesheet" href="../../../netbeans.css"></head> | |
| <body> | |
| <h1>Getting Started with RESTful Web Services</h1> | |
| <p>REpresentational State Transfer (REST) is an architectural style for | |
| distributed hypermedia systems, such as the World Wide Web. Central to the RESTful | |
| architecture is the concept of resources identified by universal resource identifiers (URIs). | |
| These resources can be manipulated using a standard interface, such as HTTP, | |
| and information is exchanged using representations of these resources. In this tutorial, | |
| you first learn a bit about REST and then you are shown how NetBeans IDE supports | |
| this architectural style.</p> | |
| <p><b>Contents</b></p> | |
| <img src="../../../images_www/articles/71/netbeans-stamp.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.1" title="Content on this page applies to NetBeans IDE 7.1"> | |
| <ul> | |
| <!-- <li><a href="#introduction">Exercise 0: Install and configure the tutorial environment</a></li>--> | |
| <li><a href="#introduction"> | |
| Introduction</a></li> | |
| <li><a href="#entity-classes">RESTful Web Services, Persistence, and Entity Classes</a></li> | |
| <li><a href="#create-services-from-db"> | |
| Creating RESTful Web Services from a Database</a> | |
| <ul> | |
| <li><a href="#create-project" >Creating the Project</a></li> | |
| <li><a href="#entities-and-services" >Generating Entity Classes and RESTful Services</a></li> | |
| </ul></li> | |
| <li><a href="#test-rest"> | |
| Testing the RESTful Web Services</a></li> | |
| <li><a href="#add-google-map"> | |
| Adding a Google Map Feature</a></li> | |
| <li><a href="#rest-spring">RESTful Web Services in the Spring Framework</a> | |
| <ul> | |
| <li><a href="#create-spring-webapp">Creating a Java Web Application | |
| With the Spring Framework</a></li> | |
| <li><a href="#add-aopalliance">Adding aopalliance.jar to the Project</a></li> | |
| <li><a href="#create-spring-restful-services">Creating RESTful Services in | |
| the Spring-enabled Project</a></li> | |
| <li><a href="#spring-errors">Compilation Errors</a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| <p><b>To follow this tutorial, you need the following software and resources.</b></p> | |
| <table> | |
| <tbody> | |
| <tr> | |
| <th class="tblheader" scope="col">Software or Resource</th> | |
| <th class="tblheader" scope="col">Version Required</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a target="_blank" href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td> | |
| <td class="tbltd1">Java EE download bundle</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a target="_blank" href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a></td> | |
| <td class="tbltd1">version 6 or 7</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1">Java EE-compliant application server</td> | |
| <td class="tbltd1"><p><a href="http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html" target="_blank">Oracle WebLogic Server 11g-12c</a>, <br> | |
| or | |
| GlassFish Server Open Source Edition 3.x.<br> | |
| (Does not work on Tomcat unless EJB support plugin is installed to Tomcat)</p> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><p>The jdbc/sample database on <br> | |
| Java DB (Derby) database server or MySQL <br>database server </p></td> | |
| <td class="tbltd1"><p>On Java DB (Derby), The jdbc/sample database is generated by NetBeans IDE <br> | |
| when you install the IDE | |
| with the GlassFish application server.</p> | |
| <p>On MySQL, the IDE populates the sample database after you create it on the MySQL server from within the IDE. </p></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p class="notes">The GlassFish server can be installed with the Web and Java EE distribution of NetBeans IDE. Alternatively, you can visit the <a href="http://glassfish.dev.java.net/public/downloadsindex.html">the GlassFish server downloads page</a>.</p> | |
| <p class="alert"><strong>Important: </strong>Java EE 6 projects require GlassFish Server 3.x or Oracle WebLogic Server 12c.</p> | |
| <!-- =========================================== --> | |
| <h2><a name="introduction"></a> | |
| Introduction</h2> | |
| <p>RESTful web services are services built using the RESTful architectural style. | |
| Building web services using the RESTful approach is emerging as a popular | |
| alternative to using SOAP-based technologies for deploying services on the | |
| internet, due to its lightweight nature and the ability to transmit data | |
| directly over HTTP.</p> | |
| <p>The IDE supports rapid development of RESTful web services using | |
| JSR 311 - Java API for RESTful Web Services (JAX-RS) and Jersey, | |
| the reference implementation for JAX-RS.</p> | |
| <p>For detailed information, refer to the following:</p> | |
| <ul> | |
| <li><a target="_blank" href="http://jcp.org/en/jsr/detail?id=311">JSR 311: JAX-RS: The Java API for RESTful Web Services</a> | |
| <li><a href="http://jersey.dev.java.net/">Jersey, the open source JAX-RS (JSR 311) Reference Implementation for building RESTful Web services</a> | |
| </ul> | |
| <p>In addition to building RESTful web services, the IDE also supports testing, | |
| building client applications that access RESTful web services, and generating code | |
| for invoking web services (both RESTful and SOAP-based.)</p> | |
| <p>Here is the list of RESTful features provided by the IDE:</p> | |
| <ol> | |
| <li>Rapid creation of RESTful web services from JPA entity | |
| classes and patterns.</li> | |
| <li>Rapid code generation for invoking web services such as | |
| Google Map, Yahoo News Search, and StrikeIron web services by | |
| drag-and-dropping components from the Web Services manager in the Services window.</li> | |
| <li>Generation of RESTful Java Clients for services registered in the Web Services manager.</li> | |
| <li>Test client generation for testing RESTful web services.</li> | |
| <li>Logical view for easy navigation of RESTful web service implementation | |
| classes in your project.</li> | |
| <li> Fully integrated Spring framework, providing Spring transaction handling.</li> | |
| </ol> | |
| <p>In | |
| this | |
| tutorial, you will be shown how the IDE supports you in generating, | |
| implementing, and testing | |
| RESTful web services. | |
| <!-- =========================================== --> | |
| <h2><a name="entity-classes"></a> RESTful Web Services, Persistence, and Entity Classes </h2> | |
| <p>RESTful web services in Java rely on the <a href="http://en.wikipedia.org/wiki/Java_Persistence_API" target="_blank">Java Persistence API</a> | |
| to communicate with a database. Specifically, RESTful web services rely on <em>entity classes</em> | |
| and a <em>persistence unit</em>, as defined in the Persistence API. Entity classes are | |
| Java classes that map to objects in a relational database. According | |
| to <a href="http://download.oracle.com/javaee/5/tutorial/doc/bnbqa.html" target="_blank">The Java EE5 Tutorial</a>, | |
| "An entity is a lightweight persistence domain object. Typically | |
| an entity represents a table in a relational database, and each entity | |
| instance corresponds to a row in that table." A persistence unit | |
| consists of the set of entity classes, the data source, the persistence | |
| provider, and the persistence unit's own name, as defined in a <tt>persistence.xml</tt> file. </p> | |
| <p>You can use NetBeans IDE either to create entity classes and RESTful web services in the same process, | |
| or you can use the IDE to create RESTful web services from existing entity classes. | |
| In this tutorial, you use the RESTful Services from Database wizard to generate entity classes and RESTful web | |
| services in the same process. The wizard automatically generates the persistence unit.</p> | |
| <!-- =========================================== --> | |
| <h2><a name="mysql"></a>Using a MySQL Database Server </h2> | |
| <p>If you use the MySQL database server instead of JavaDB (Derby), you need to register the database server with the IDE and add the <tt>sample</tt> database to the server.</p> | |
| <p><strong>To use a MySQL database server with this tutorial:</strong></p> | |
| <ol> | |
| <li>Register your MySQL server in the IDE, if the server is not registered. To register a MySQL server, go to the IDE's Services window, right-click the Databases node, and select Register MySQL server. <br> | |
| <img src="../../../images_www/articles/71/websvc/rest/register-mysql-server.png" height="164" width="248" class="margin-around b-bottom" alt="Register MySQL Server option in Services window"></li> | |
| <li> | |
| <p>A dialog opens in which you type the configuration details of your MySQL server, including administrator user name and password. See "Configuring MySQL Server Properties" in <a href="../../docs/ide/install-and-configure-mysql-server.html">Connecting to a MySQL Database</a>.</p> | |
| <img src="../../../images_www/articles/71/websvc/rest/basic-mysql-properties.png" height="264" width="402" alt="Basic properties of the MySQL server you are registering in the IDE" class="margin-around"></li> | |
| <li>Start the MySQL server and connect to it. See "Starting the MySQL Server" in <a href="../../docs/ide/install-and-configure-mysql-server.html">Connecting to a MySQL Database</a>. </li> | |
| <li>Right-click the MySQL server node and select Create Database. The Create MySQL Database dialog opens. <br> | |
| <img src="../../../images_www/articles/71/websvc/rest/create-database.png" alt="Create Database context menu option" height="229" width="261" class="margin-around b-bottom"> </li> | |
| <li>Type <tt>sample</tt> as the new database name. Grant full access to your root user, or a user of your choice.<br> | |
| <img src="../../../images_www/articles/71/websvc/rest/new-database-name.png" height="136" width="404" class="margin-around" alt="New Database Name dialog filled out"> </li> | |
| <li>Click OK. A dialog opens informing you that <tt>sample</tt> is the name of a sample database, and asking you if you want to create the tables, objects, and data for this database.<br><img src="../../../images_www/articles/71/websvc/rest/create-sample-contents.png" alt="Prompt to populate database with sample data" height="139" width="543" class="margin-around"> </li> | |
| <li>Click Yes. The IDE creates and populates the database, and adds a connection to the database.<br><img src="../../../images_www/articles/71/websvc/rest/generated-db.png" height="130" width="383" alt="Generated sample database and database connection in Services window" class="margin-around b-bottom"> </li> | |
| </ol> | |
| <h2><a name="create-services-from-db"></a>Creating RESTful Web Services from a Database </h2> | |
| <p>The goal of this exercise is to create a project and generate entity classes and RESTful web services from a database.</p> | |
| <p>This section uses the JavaDB (Derby) database and the jdbc/sample data source. JavaDB is included with the SDK. | |
| The jdbc/sample data source is generated by NetBeans IDE automatically when you install the IDE together with GlassFish.</p> | |
| <div class="indent"> | |
| <!-- =========================================== --> | |
| <h3><a name="create-project"></a>Creating the Project</h3> | |
| <p>To create RESTful web services, you need a Java Web application project. </p> | |
| <p><strong>To create the project: </strong></p> | |
| <ol> | |
| <li><p>Choose File > New Project (Ctrl-Shift-N on Linux and Windows, ⌘-Shift-N on MacOS). Under Categories, select Java Web. | |
| Under Projects, select Web Application. Click Next. | |
| The New Web Application wizard opens.</p> | |
| <p>Alternatively, you can create a Maven Web Application. Choose File > New Project (Ctrl-Shift-N on Linux and Windows, ⌘-Shift-N on MacOS). Under Categories, select Maven. Under Projects, select Maven Web Application and click Next. </p> | |
| </li> | |
| <li>Under Project Name, enter <tt>CustomerDB</tt>. Click Next.</li> | |
| <li>Select either EE 6 or EE 5. Under Server, select the server you want to use, but note that EE 6 projects require GlassFish server 3 or later. Click through the remaining options and click Finish. | |
| <p class="alert"><b>Important for Maven Projects:</b> You cannot set the server when you create a Maven web application. However, you have to set the server before you can create a persistence unit. Therefore, after you create the Maven web application, open the project's Properties and set the server in the Run properties. To open the project's Properties, right-click on the Project node and select Properties from the context menu.</p> | |
| </li> | |
| </ol> | |
| <!-- =========================================== --> | |
| <h3><a name="entities-and-services"></a>Generating Entity Classes and RESTful Services</h3> | |
| <p>When you have a Java web application, add entity classes and RESTful web services to the project.</p> | |
| <p><strong>To generate entity classes and RESTful web services: </strong></p> | |
| <ol> | |
| <li>Right-click the <tt>CustomerDB</tt> node and | |
| choose New > Other > Web Services > RESTful Web Services from Database. The New RESTful Web Service wizard opens, on the Database Tables panel.<br> <img src="../../../images_www/articles/71/websvc/rest/open-wizard.png" alt="RESTful Web Services from Database option in menu" height="396" width="600" class="margin-around"> </li> | |
| <li>In the Database Tables panel, if you are using the GlassFish server, select the <tt>jdbc/sample</tt> data source from the Data Source drop-down field. | |
| <p>If you are using Tomcat, select jdbc:derby://localhost:1527/sample. If the Derby database server does not start automatically, you need to start it from the Databases tab in the Services window.</p> | |
| <p class="notes"><b>Note for MySQL users:</b> You have to create a new data source. Select New Data Source, give it an arbitrary descriptive name, and select the <tt>jdbc:mysql://localhost:3306/sample</tt> database connection. You created this connection when you created the sample database on MySQL. <br><img src="../../../images_www/articles/71/websvc/rest/new-mysql-datasource.png" alt="New data source using mysql connection" height="402" width="594" class="margin-around"></p> | |
| </li> | |
| <li> Under Available Tables, select CUSTOMER and then click Add. The DISCOUNT_CODE | |
| table, which has a relationship with the CUSTOMER table, is also automatically | |
| added to the Selected Tables list. If you are using a MySQL database, the MICRO_MARKET | |
| table is also added. You now | |
| see the following (Derby version): <br> | |
| <br> | |
| <img border="1" src="../../../images_www/articles/71/websvc/rest/select-tables.png" height="381" width="556" alt="Database Tables panel of New Entity Classes from Database wizard, showing CUSTOMER and DISCOUNT_CODE tables selected" title="Database Tables panel of New Entity Classes from Database wizard, showing CUSTOMER and DISCOUNT_CODE tables selected" class="margin-around"></li> | |
| <li>Click Next. The Entity Classes page opens. Under Package, type <tt>entities</tt>. You now see the following (Derby version). | |
| <p class="notes"><b>Note:</b> The RESTful Web Services from Database wizard automatically generates JAXB annotations. If you generate entity classes for an EE6 application with the Entity Classes from Database wizard, and you might later want to create RESTful web services from those entity classes, make sure the Generate JAXB Annotations box is checked. You can also add JAXB annotations by hand to entity classes before running the RESTful Web Services from Entity Classes wizard. For more information, see <a href="http://netbeans.dzone.com/nb-generate-simpler-rest" target="_blank">NetBeans to Generate Simpler RESTful Web Services</a>. </p> | |
| <img src="../../../images_www/articles/71/websvc/rest/entity-classes.png" alt="Entity Classes panel of RESTful Web Services from Database wizard, showing package name" class="margin-around"></li> | |
| <li>Click Next. The Generated Classes panel opens. | |
| In this panel you can set the location of the RESTful web service classes that the IDE generates for your project. The Generated Classes panel differs between EE5 and EE6 RESTful web services, because EE5 projects include JPA controller classes but EE6 web services generate service classes as stateless session beans, instead.<br><img src="../../../images_www/articles/71/websvc/rest/generated-classes-ee5.png" alt="Generated classes page for EE5 project" width="489" height="268" class="margin-around"> | |
| <p align="center"> </p> | |
| </li> | |
| <li>Accept the default packages and locations and click Finish. The IDE generates entity classes. Then a dialog opens, asking how you want to register RESTful resources. For EE5 projects, you have the (default) choice of using a Jersey RESTful servlet adaptor in the <tt>web.xml</tt> deployment descriptor, or of hand coding your own solution. For EE6 projects, you have the additional choice (default) of using a subclass of <tt>javax.ws.rs.core.Application</tt>. | |
| <p class="alert"><strong>Spring framework applications:</strong> Register the RESTful resources in the <tt>web.xml</tt> deployment descriptor. Do NOT use <tt>javax.ws.rs.core.Application</tt>.</p> | |
| <img src="../../../images_www/articles/71/websvc/rest/rest-resource-config-ee6.png" alt="Options for registering RESTful resources, EE6 application" height="364" width="528" class="margin-around"></li> | |
| </ol> | |
| </div> | |
| <p>The IDE now generates the RESTful web services. When the IDE is finished, look in the Projects window. The generated entity classes are in the <tt>entities</tt> package. Services are in the <tt>service</tt> package. For an EE5 project, there are JPA controller classes in the <tt>controller</tt> package and a <tt>web.xml</tt> deployment descriptor under Configuration Files. </p> | |
| <p class="alert"><b>Caution:</b> The IDE might prompt you to Resolve Reference Problems for the project. In this case, right-click the CustomerDB project node and select Resolve Reference Problems. This issue can happen when the service is the first Jersey application to run on a WebLogic installation. In this case, the IDE solves the reference problem by copying the Jersey libraries to the server.</p> | |
| <p><img src="../../../images_www/articles/71/websvc/rest/ee5-complete-project.png" alt="Complete EE5 RESTful service from database project" class="margin-around"></p> | |
| <p>EE6 RESTful web services from a database instantiate <tt>EntityManager</tt> in each service class. This removes the need for JPA controller classes and generates simpler code.</p> | |
| <p><img src="../../../images_www/articles/71/websvc/rest/ee6-project-complete.png" alt="Complete EE6 RESTful service from database project" height="380" width="367" class="margin-around"></p> | |
| <!-- ===================================================================================== --> | |
| <h2><a name="test-rest"></a> | |
| Testing the RESTful Web Services</h2> | |
| <p>The goal of this exercise is to try out your application.<br> | |
| </p> | |
| <ol><li>Right-click the project node and choose Test RESTful Web Services. A dialog opens asking if you want to generate the test client inside the service project or in another Java web project. This option lets you work around security restrictions in some browsers. You can use any Web project, as long as it is configured to deploy in the same server domain as the CustomerDB project.<br> | |
| <img src="../../../images_www/articles/71/websvc/rest/configure-test-client.png" alt="Dialog for selecting whether to generate a test client locally or in another Java Web project deployed to the same domain" height="293" width="565" class="margin-around"></li> | |
| <li>Select where to generate the test client and click OK. The server starts and the application is deployed. | |
| When deployment is complete, the browser displays your application, with a link for | |
| each of the web services. | |
| <p class="notes">If the output window shows an error message that one or more classes fails to exist and the project does not build, add the Jersey libraries to the compile-time libraries. Right-click the project node and select Properties. In the Properties tree menu, select Libraries. Click Add Library and browse for the Jersey libraries.</p> | |
| <img class="margin-around" border="1" src="../../../images_www/articles/71/websvc/rest/test-rest1.png" alt="RESTful web service tester landing page in browser" title="RESTful web service tester landing page in browser"> | |
| <p>On the left-hand side is the set of root resources. Here they | |
| are named <tt>entities.customer</tt> and <tt>entities.discountCodes</tt>.</p> | |
| </li> | |
| <li>Click the <tt>entities.customer</tt> node. In the "Choose method to test" field, select either GET (application/json) or GET (application/xml). Click Test. | |
| The test client sends a request and displays the result in the Test Output section. The test client dispays the Raw View by default. The following image shows the response to an application/xml request.<br> | |
| <img src="../../../images_www/articles/71/websvc/rest/test-rest-raw.png" alt="Raw view window in RESTful web service tester" class="margin-around"></li> | |
| </ol> | |
| <p>There are 5 tabs in the Test Output section. </p> | |
| <ul> | |
| <li>The Tabular View is a flattened view that displays all | |
| the URIs in the resulting document. Currently this view only displays a warning that Container-Containee relationships are not allowed.</li> | |
| <li>The Raw View displays | |
| the actual data returned. Depending on which mime type | |
| you selected (<tt>application/xml</tt> or <tt>application/json</tt>), | |
| the data displayed will be in either XML or JSON format, respectively. </li> | |
| <li>The Sub Resource tab shows the URLs of the root resource and sub resources. When the RESTful web service is based on database entity classes, the root resource represents the database table, and the sub resources represent the columns.</li> | |
| <li>The Headers tab displays the HTTP header information. </li> | |
| <li>The HTTP Monitor tab displays the actual HTTP requests | |
| and responses sent and received. </li> | |
| </ul> | |
| <p>Exit the browser and return to the IDE.</p> | |
| <!-- ===================================================================================== --> | |
| <h2><a name="add-google-map"></a> | |
| Adding a Google Map Feature</h2> | |
| <p>The goal of this exercise is to add Google map | |
| functionality to our RESTful web services.</p> | |
| <ol> | |
| <li>Open the <tt>CustomerRESTFacade</tt> class (EE 5) or <tt>CustomerFacadeREST</tt> class (EE 6) | |
| in the editor. </li> | |
| <li><a name="add_method_step"></a>Add the following method to the class: | |
| <pre>@GET | |
| @Produces("text/html") | |
| public String getGoogleMap() { | |
| // Drag and drop the getGoogleMap operation here | |
| return ""; | |
| }</pre> | |
| </li> | |
| <li><a name="get_google_map_key"></a>Sign up for a Google map key at <a target="_blank" href="http://www.google.com/apis/maps/signup.html">http://www.google.com/apis/maps/signup.html</a>. The Google map key request dialog has a field for your website's URL. Type <tt>http://localhost:8080</tt> in that field.</li> | |
| <li>In the IDE, open the Services tab and expand the Web Services node. Under Web Services, expand Google. Under Google, expand Map Service.<br> | |
| <br><img class="margin-around" alt="services view showing google map service" title="Services view showing Google map service" src="../../../images_www/articles/71/websvc/rest/google-saas.png"></li> | |
| <li>Drag the getGoogleMap item and drop it into the body of the <tt>getGoogleMap</tt> method you created in <a href="#add_method_step">Step 2</a>, just before the <tt>return = "";</tt> line. The Customize getGoogleMap SAAS dialog opens. Accept the defaults and click OK. | |
| <p>The IDE adds the following <tt>try</tt> block to the <tt>getGoogleMap</tt> method. | |
| <pre>@GET | |
| @Produces("text/html") | |
| public String getGoogleMap() { | |
| // Drag and drop the getGoogleMap operation here | |
| try { | |
| String address = "16 Network Circle, Menlo Park"; | |
| java.lang.Integer zoom = 15; | |
| String iframe = "false"; | |
| RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe); | |
| //TODO - Uncomment the print Statement below to print result. | |
| //System.out.println("The SaasService returned: "+result.getDataAsString()); | |
| } catch (Exception ex) { | |
| ex.printStackTrace(); | |
| } | |
| return ""; | |
| } | |
| </pre> | |
| <p>The IDE also creates the packages org.netbeans.saas and org.netbeans.saas.google, which contain the following classes and resources: </p> | |
| <ul> | |
| <li><tt>RestConnection</tt> - A wrapper around HttpUrlConnection </li> | |
| <li><tt>RestResponse</tt> - A wrapper for the HTTP response</li> | |
| <li><tt>googlemapservice.properties</tt> - A properties file that stores the API key </li> | |
| <li><tt>GoogleMapService</tt> - A service wrapper containing the wrapper methods that uses RestConnection to make calls to the Google Map service.</li> | |
| </ul> | |
| <img src="../../../images_www/articles/71/websvc/rest/project-w-google-ee6.png" alt="Projects window showing packages added after get Google Map method is dropped into Customer Resource" class="margin-around"> | |
| <li>In the try block of getGoogleMap(), replace the commented-out print statement with the line <span class="examplecode"><tt>return result.getDataAsString();</tt></span>. The method now looks like this: | |
| <pre>@GET | |
| @Produces("text/html") | |
| public String getGoogleMap() { | |
| // Drag and drop the getGoogleMap operation here | |
| try { | |
| String address = "16 Network Circle, Menlo Park"; | |
| java.lang.Integer zoom = 15; | |
| String iframe = "false"; | |
| RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe); | |
| return result.getDataAsString(); | |
| } catch (Exception ex) { | |
| ex.printStackTrace(); | |
| } | |
| return ""; | |
| }</pre> | |
| </li> | |
| <li>Open <tt>googlemapservice.properties</tt>. Paste in the API key you got from Google in <a href="#get_google_map_key">Step 3</a>. | |
| Save your changes. The IDE automatically redeploys your project. | |
| <li>Refresh your browser window with the test client. </li> | |
| <li>Click <tt>entities.customer</tt> in the left sidebar. The <code>GET (text/html)</code> method appears in the "Choose method to test" field. Click Test. The GoogleMap of 16 Network Circle, Menlo Park opens in the Raw View. | |
| <br> | |
| <img src="../../../images_www/articles/71/websvc/rest/menlo-park-map.png" alt="RESTful services test page showing Google map of Menlo Park" border="1" class="margin-around"> </li> | |
| <li> | |
| <p>The Google map of the Menlo Park address appears for all customers in the database. To display the Google maps of the actual addresses of the customers, create an instance of Customer and set the address equal to a concatenation of address variables for that instance of Customer. </p> | |
| <p>Find an instance of Customer by calling the entity manager's <tt>find()</tt> method. In an EE5 service, the customer facade uses its own <code>find</code> method to call <code>CustomerJpaController</code>, which instantiates the entity manager. In an EE6 service, the customer facade uses the abstract facade to access the entity manager. The generic <tt>find()</tt> method requires explicit argument type casting to Object and an explicit entity id. The following code displays the map location of the customer with id number 1 (changes in bold):</p> | |
| <p><b>EE5 service:</b></p> | |
| <pre>@GET | |
| @Produces("text/html") | |
| public String getGoogleMap() { | |
| try { | |
| <b>Customer c = find(1); | |
| String address = c.getAddressline1() + " " + c.getAddressline2() + " " + | |
| c.getCity() + " " + c.getState() + " " + c.getZip();</b> | |
| java.lang.Integer zoom = 15; | |
| String iframe = "false"; | |
| RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe); | |
| return result.getDataAsString(); | |
| } catch (Exception ex) { | |
| ex.printStackTrace(); | |
| } | |
| <b></b> | |
| return ""; | |
| }</pre> | |
| <p><b>EE6 service:</b></p> | |
| <pre>@GET | |
| @Produces("text/html") | |
| public String getGoogleMap() { | |
| try { | |
| <b>Customer c = getEntityManager().find(Customer.class, 1); | |
| String address = c.getAddressline1() + " " + c.getAddressline2() + " " + | |
| c.getCity() + " " + c.getState() + " " + c.getZip();</b> | |
| java.lang.Integer zoom = 15; | |
| String iframe = "false"; | |
| RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe); | |
| return result.getDataAsString(); | |
| } catch (Exception ex) { | |
| ex.printStackTrace(); | |
| } | |
| <b></b> | |
| return ""; | |
| }</pre> | |
| </li> | |
| <li>Test the RESTful web services again. The customer id is specified as an argument for the <tt>find()</tt> method and the tester displays the raw view by default. For customer 1, the following map displays: | |
| <p class="tips"><strong>Tip: </strong>Try to change the id number passed as an argument to <code>getEntityManager().find(Customer.class, id)</code>. A real world client would get the value of this argument from a UI form.</p> | |
| <br><img border="1" src="../../../images_www/articles/71/websvc/rest/google-map-4.png" class="margin-around" alt="Google Map showing address of customer in database" title="Google Map showing address of customer in database"> | |
| <p class="notes"><b>Note: </b>If GoogleMaps cannot find an address, it shows a zoomed in view of the ocean.</p></li> | |
| </ol> | |
| <!-- Spring Framework --> | |
| <h2><a name="rest-spring"></a>RESTful Web Services in the Spring Framework</h2> | |
| <p>Jersey is integrated into the Spring Framework. When you create a Java Web application with the Spring framework, a REST-aware servlet is automatically created. However, Spring 3 doesn't contain aopalliance.jar, which the RESTful web service requires to inject an EntityManager object.</p> | |
| <div class="indent"> | |
| <h3><a name="create-spring-webapp"></a>Creating a Java Web Application With the Spring Framework</h3> | |
| <p>When you create the Java Web application in the New Project wizard as described in <a href="#Exercise_1">Generating Entity Classes from a Database</a>, after you select the server, click Next instead of Finish. This opens the Frameworks panel. Select Spring Web MVC, then click Finish. </p> | |
| <img src="../../../images_www/articles/71/websvc/rest/selecting-spring.png" alt="Selecting the Spring framework when creating a Java web application" class="margin-around"> | |
| <h3><a name="add-aopalliance"></a>Adding aopalliance.jar to the Project</h3> | |
| <p>Spring 3 does not contain <tt>aopalliance.jar</tt>. The application requires this library to inject EntityManager. To fix the problem you need to download this jar and add it to your classpath. See <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=193626" title="https://netbeans.org/bugzilla/show_bug.cgi?id=193626">Issue 193626</a> and the <a target="_blank" href="http://forum.springsource.org/showthread.php?t=10511" title="http://forum.springsource.org/showthread.php?t=10511">Spring forums</a>. </p> | |
| <p><strong>To add aopalliance.jar:</strong></p> | |
| <ol> | |
| <li> Download a zip archive of <tt>aopalliance.jar</tt> from <a target="_blank" href="http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/" title="http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/" rel="nofollow">http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/</a>.</li> | |
| <li>Unzip the archive to the location of your choice.</li> | |
| <li>In the IDE's Projects window, right-click your Spring RESTful Web Service project node. The context menu opens.<br> | |
| <img src="../../../images_www/articles/72/websvc/rest/properties-node.png" height="537" width="340" alt="Context menu showing properties node" class="margin-around"></li> | |
| <li>Select Properties. The Properties dialog opens.</li> | |
| <li>In the Categories pane, select Libraries. Click Add JAR/Folder. A file system browser opens.</li> | |
| <li>Browse for <tt>aopalliance.jar</tt>. Use the absolute path reference. Click Open.<br> | |
| <img src="../../../images_www/articles/72/websvc/rest/browse-for-aopalliance.png" alt="Browsing for aopalliance.jar" height="404" width="586" class="margin-around"></li> | |
| <li>The <tt>aopalliance.jar</tt> file is now included in your libraries. Click OK. <br> | |
| <img src="../../../images_www/articles/72/websvc/rest/libraries.png" alt="Library properties showing added aopalliance.jar" height="461" width="600" class="margin-around"> </li> | |
| </ol> | |
| <h3><a name="create-spring-restful-services"></a>Creating RESTful Services in the Spring-enabled Project</h3> | |
| <p>After you create a Java web application with the Spring framework and add <tt>aopalliance.jar</tt> | |
| to the project's classpath, run the RESTful Web Service from Database wizard as described in <a href="#entities-and-services">Generating Entities and Services</a>. However, do NOT register RESTful resources with a subclass of <tt>javax.ws.rs.core.Application</tt>. Instead use the <tt>web.xml</tt> deployment descriptor. The Spring framework generates a <tt>web.xml</tt> deployment descriptor in all cases.</p> | |
| <img src="../../../images_www/articles/71/websvc/rest/ee6-rest-configuration.png" alt="Options for registering RESTful resources, web.xml chosen" height="319" width="486" class="margin-around"> | |
| <p>For more about the features of Spring framework projects in NetBeans IDE, see <a href="../../docs/web/quickstart-webapps-spring.html">Introduction to the Spring Framework</a>.</p> | |
| <h3><a name="spring-errors"></a>Compilation Errors</h3> | |
| <p>You might have compilation errors in the generated service classes. You see these errors if you create the RESTful services before you add <tt>aopalliance.jar</tt> to the classpath. </p> | |
| <p><strong>To fix compilation errors in service classes:</strong></p> | |
| <ol> | |
| <li>Make certain that you add <tt>aopalliance.jar</tt> to the classpath, as described in <a href="#add-aopalliance">Adding aopalliance.jar to the Project</a>.</li> | |
| <li>In the IDE's top menu bar, click Edit and select Find in Projects...</li> | |
| <li>Search for all occurrences of the <tt>@Error</tt> annotation in the project.<br> | |
| <img src="../../../images_www/articles/72/websvc/rest/find-error.png" alt="Find in Projects dialog showing search for the @Error annotation" height="307" width="431" class="margin-around"></li> | |
| <li>Delete every <tt>@Error</tt> line from the code.<br> | |
| <img src="../../../images_www/articles/72/websvc/rest/error-lines.png" alt="Search results for @Error, with one line highlighted and about to be deleted" height="558" width="590" class="margin-around"></li> | |
| </ol> | |
| </div> | |
| <div class="feedback-box" ><a href="/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20REST%20Services%20in%20NetBeans%20IDE%20">Send Feedback on This Tutorial</a></div> | |
| <br style="clear:both;"> | |
| <h2><a name="seealso"></a>See Also</h2> | |
| <p>For more information about using NetBeans IDE to develop Java EE applications, see the following resources: | |
| </p> | |
| <ul> | |
| <li><a href="http://netbeans.dzone.com/nb-generate-simpler-rest" target="_blank">NetBeans to Generate Simpler RESTful Web Services</a></li> | |
| <li><a href="../../72/websvc/jersey-rcp-client.html">Creating RESTful Service Clients in NetBeans Modules</a></li> | |
| <li><a href="../../trails/web.html">Web Services Learning Trail</a></li> | |
| <li>YouTube: <a target="_blank" href="http://www.youtube.com/watch?v=cDdfVMro99s" title="RESTful Web Services, Building and Deploying (Part 1)">RESTful Web Services, Building and Deploying (Part 1)</a></li> | |
| <li>YouTube: <a target="_blank" href="http://www.youtube.com/watch?v=_c-CCVy4_Eo" title="NetBeans RESTful Testing and Invoking RESTful Resources (Part 2)">NetBeans RESTful Testing and Invoking RESTful Resources (Part 2)</a></li> | |
| </ul> | |
| <p>To send comments and suggestions, get support, and keep informed about the latest | |
| developments on the NetBeans IDE Java EE development features, <a href="../../../community/lists/top.html">join | |
| the nbj2ee@netbeans.org mailing list</a>.</p> | |
| </body> |