Bắt đầu với IBM Websphere smash - p 19 pot

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 WebSpher

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 trustkey-store 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

Testing and Documentation

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

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

Figure 7.2 Dependency selection

Table 7.6 Documentation Annotations

@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 Verify that the new restdoc module is shown in your dependency list.

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

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

@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”

},

]

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

Figure 7.4 RESTDoc list of methods

Figure 7.5 Test resource GET method

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

Figure 7.7 Resource response to the DELETE method

Figure 7.6 GET method response

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

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

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

Database Access