ptg 162 Chapter 7 REST Programming Let’s show these settings in a real-world setting (see Listing 7.10). In our secure application, we need to secure all REST resources. Here are the relevant contents of our zero.config file. In this case, we are completely disabling the non-SSL listener and defining our SSL-specific settings. Listing 7.10 /config/zero.config—SSL-Only Configuration Sample /config/http/port = 0 /config/https/port = 443 /config/https/sslconfig = { "keyStore": "./config/key.jks", "keyStorePassword": "<xor>JTotMC8+LCw=", "keyStoreType": "JKS" } Refer to Chapter 9, “Security Model,” for more information on setting up your actual key- store and truststore values, as these are specific to your Java environment. For more information on setting up SSL, refer to the following resources. For IBM Java key management using the ikeyman tool, see http://download.boulder.ibm.com/ibmdl/pub/ software/dw/jdk/security/50/GSK7c_SSL_IKM_Guide.pdf. For Sun’s keytool utility, refer to http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html#CreateKeystore. For another good resource for defining a secure environment using keystores, see the “Using the Java Secure Socket Extension in WebSphere Application Server” article from the IBM WebSphere Developer Technical Journal by Messaoud Benantar at http://www.ibm.com/developerworks/ websphere/techjournal/0502_benantar/0502_benantar.html. Although we are providing refer- ences to more information on SSL, see the following articles for IBM at http://www.ibm.com/ developerworks/java/jdk/security/50/secguides/jsse2Docs/JSSE2RefGuide.html, and from Sun at http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html. If you are not ready to purchase a valid certificate from a recognized certificate authority, you can still move forward in your development using a local dummy keystore. Simply include the zero.core.webtools dependency, and a dummy keystore is automatically available for use. Please refer to Chapter 9 for more details. Testin g and Documenta tion After you have written all of your REST services, you now have the daunting task of creating a test environment to validate all your resources and the methods supported with each. Sure, any competent programmer can create a Dojo application to test each use case and display the results and response codes. You could even use external tools such as the Poster plugin for Firefox or similar utilities. Now that you’ve gotten the tools to test your services, you need to document each service resource and its methods. Nobody likes documentation, but you know it needs to be done, and Download from www.wowebook.com ptg Testing a n d D ocumen t a t i o n 163 Figure 7.1 Adding RESTDoc tooling more important, it needs to remain accurate and current to the actual code. The only thing worse than no documentation is wrong documentation! Wouldn’t it be nice if WebSphere sMash provided a tool that could examine our resources and create a test environment for us? Or maybe it could even generate our documentation, too? I guess you know where I’m heading with this. All we need to do is supply some annotation com- ments directly in the code, where it’s much more likely to stay current and accurate, and the RESTDoc module available in WebSphere sMash will create both clean documentation and a basic test environment for us. Maybe we can take Friday off after all! To begin using the RESTDoc tool, add the latest available version of the zero.restdoc. webtools module as a dependency to your project. If you have not previously downloaded the RESTDoc tool into your repository, follow these steps to pull it down. This will need to be done only once. Under the Eclipse environment, open the /config/ivy.xml file and click Add. For App- Builder, click on the Dependencies tab: 1. Click the Manage Repositories button to open the module management window. 2. In the top right, search for the zero:zero.restdoc.webtools module, as shown in Figure 7.1. 3. After the search is complete and you see the desired module, click the Download button to bring it into your local repository. 4. When the download completes, close the module management window. 5. Back at the Dependency Selection window, locate and select the zero:zero.restdoc. webtools module, as shown in Figure 7.2. Download from www.wowebook.com ptg 164 Chapter 7 REST Programming Figure 7.2 Dependency selection Table 7.6 Documentation Annotations Annotation Description Example @success The status code returned upon successful completion of the service. There can be 0+ success codes defined. 200 is the default. @success 200 @success 201 @error The status code returned when an error condition occurs. There can be 0+ error codes defined. @error 500 @error 503 Note that there may also be a zero:zero.restdoc module shown in your repository. You do NOT need to add this particular module because it’s used by the CLI, as we’ll see later. 6. Veri fy t ha t t he new r es tdoc m od ul e i s show n in y ou r d ependen cy l is t. 7. For Eclipse, save and close your ivy.xml file. For AppBuilder, simply switch back to your File Editor view. Our next step is to annotate each event method within our resources. Table 7.6 shows the annotations that can be used to document your services. Descriptive text can be applied after any annotation to aid in your documentation. Download from www.wowebook.com ptg Testing a n d D ocumen t a t i o n 165 Let’s add some RESTDoc annotations to our sample car resource and see how it is processed. In Listing 7.11, we document our updates to the onRetrieve method of our car resource. Listing 7.11 /app/resources/car.groovy - RESTDoc Annotations /** * /app/resources/car.groovy * GET (Singleton), with possible binding extensions. * * @success 200 Returns car specific data for a given ID * @failure 503 System is down for maintenance * @format application/json * @example * { * id: id, * make: String, * model: String, * year: YYYY, * number: XX, * driver: { * // Driver object * }, * team: { * // Team object Table 7.6 Documentation Annotations Annotation Description Example @format Defines the Content-Types that will be returned on a GET operation, or the expected data format to be received on a POST action. Standard mime type should be used, but any value is acceptable. @format text/xml @example Displays a sample of the expected response data (GET), or incoming request data (POST/PUT). This is informational only and you can show data in any freeform format. @example [ { id: 1, name: “joe” }, ] Download from www.wowebook.com ptg 166 Chapter 7 REST Programming Figure 7.3 RESTDoc view of resources * } * } * */ def onRetrieve() { // } One item that may seem overly obvious, but can easily trip you up, is to not use block-level comments (/* */) within the example section of the RESTDoc. This will corrupt the overall comment block and cause all sorts of problems. It’s fine to use a regular inline comment, how- ever, as shown in the preceding example. At this point, we have all the pieces necessary to view our service documentation and per- form basic unit test of the services themselves. Start (or restart) the application, and open your browser to http://localhost:8080/resources/restdoc; you should see a list of all available resources in your application, similar to Figure 7.3. When you click on one of the resources, you will see all the REST methods supported by this service. In Figure 7.4, you can see that we support all the methods. For each method, you can see the URL pattern, support response format(s), and expected success code. Clicking on a URI for a method enables you to perform an interactive test of that method. When testing a method, you will be prompted for any required arguments, such as the ID for singleton requests. You have the option to add custom headers for services that support con- tent negotiation. In Figure 7.5, we clicked on the single retrieve GET method and have entered an ID to pass into the service. After we submit the request, the response is shown, as in Figure 7.6. Download from www.wowebook.com ptg Testing a n d D ocumen t a t i o n 167 Figure 7.4 RESTDoc list of methods Figure 7.5 Tes t re source GE T met hod In the final test case, we want to see an error condition. Because we don’t actually want to allow DELETE actions, we send back a 405 (BAD_METHOD) error status, as shown in Figure 7.7. If we click on the format for a method, the examples we specified will be displayed, as shown in Figure 7.8. Download from www.wowebook.com ptg 168 Chapter 7 REST Programming Figure 7.7 Resource response to the DELETE method Figure 7.6 GET method response Download from www.wowebook.com ptg Testing a n d D ocumen t a t i o n 169 Figure 7.8 Format for the GET method Before we close out our discussion of RESTDoc, there are few things worth mentioning. First, if you don’t want to include the webtools version of RESTDoc that allows a real-time introspection of the services and methods, you can use the version that’s available from the command line. Just run zero restdoc from your project directory. This creates a static version of the resources into a newly created /public/docs directory. This will still allow interactive testing of the services in your project but will not show any changes made unless you rerun the restdoc command from the CLI. The most important thing to remember about RESTDoc is the power it gives a web user. It is critical that you protect either the /resources/restdoc or the /docs directory depending on what you go into production with to prevent normal users to access these tools. It’s simply way too easy to make irrevocable and potentially disastrous changes to your data with RESTDoc. You must weigh the advantages of being able to quickly test and examine your resources with the potential for destruction in deciding if you should include the RESTDoc resource in your application. The RESTDoc modules do not cover complex scenarios and currently do not properly deal with compound resources defined through bonding files. However, it’s still a useful utility that you should keep in your WebSphere sMash toolkit. Using the RESTDoc tool provides both a clean way to document your services, and a nice, easy, and consistent interactive test environment. Download from www.wowebook.com ptg Conclusion We’ve spent a good deal of time going over REST, from both a standard protocol scenario and in its use within WebSphere sMash. REST is quickly becoming the preferred protocol for use in rich client applications and also as an accepted alternative for the more complex Service-Oriented Architecture (SOA) implementations, such as SOAP Web Services and Remote Procedure Calls (RPC). WebSphere sMash is perfectly positioned to act as the RIA server environment and also as a standalone REST service layer. Having a solid understanding of REST concepts and how the WebSphere sMash resource events support REST will give you an upper hand in creating applica- tions for today’s requirements. 170 Chapter 7 REST Programming Download from www.wowebook.com ptg 171 Introduction There is no doubt about it—the most common and critical part of any application is quick and efficient access to relational data. The relational database model has endured all the object- oriented thinking of the past couple decades and is as strong as ever. From the small company, all the way up to the largest enterprises, virtually everyone uses relational databases to persist com- pany data. In this chapter, we cover how to utilize the tools available within WebSphere sMash to work with this data. For simple applications, WebSphere sMash provides a deceptively simple data access layer called the Zero Resource Model (ZRM) that automatically handles the management of tables, and the resources to access and modify these tables using RESTful access patterns. For more involved applications, in which you need to provide complex selection and modifier statements, WebSphere sMash provides the pureQuery layer that sits on top of the standard JDBC API. With PureQuery, WebSphere sMash manages your connections and other resource handlers for you. All you need to be concerned with is defining your statements and working with the data. Finally, for the ugly applications, in which you need to carefully control your database connections and other resources, you can always fall back to traditional JDBC access. WebSphere sMash makes working with relation databases a breeze. Be forewarned, how- ever—when you start using WebSphere sMash to access your databases, you’ll never want to go back to any other platform! Let’s learn how to juggle data like a crazed chainsaw-wielding clown in a two-bit traveling circus. Ignore those nightmare-inducing images you may be visual- izing right about now. Hmmm Maybe that’s what happens to those grumpy old database administrators. C H A P T E R 8 Database Access Download from www.wowebook.com . Socket Extension in WebSphere Application Server” article from the IBM WebSphere Developer Technical Journal by Messaoud Benantar at http://www .ibm. com/developerworks/ websphere/ techjournal/0502_benantar/0502_benantar.html applications and also as an accepted alternative for the more complex Service-Oriented Architecture (SOA) implementations, such as SOAP Web Services and Remote Procedure Calls (RPC). WebSphere. how to utilize the tools available within WebSphere sMash to work with this data. For simple applications, WebSphere sMash provides a deceptively simple data access layer called the Zero Resource