GlassFish - World's first Java EE 7 Application Server


RADK Project

RESTful web services module

RESTful is not only over HTTP, it is independent of the protocol...

There are some API's to do RESTful: REST.API, Restlet, Jersey, etc. The solution provided in this project is using Jersey.

This module will generate automatically the RESTful web services according to the tables selected from the database schema.

It will generate one function for each HTTP method: GET, PUT, POST and DELETE for each selected table

GET

The GET method is implemented to fetch data from the tables and send it to the client in json and xml format, it will receive the requirement from the web client in the URIs: 

http://sample.com/myapplication/RestMytable/mytable/{myId}/format  
 http://sample.com/myapplication/RestMytable/mytable/{myId}/
 http://sample.com/myapplication/RestMytable/mytables
e.g.
   http://sample.com/RADKuniversity/RestStudent/student/005801234/json
   http://sample.com/RADKuniversity/RestStudent/student/005801234/xml
   http://sample.com/RADKuniversity/RestStudent/student/005801234/
   http://sample.com/RADKuniversity/RestStudent/students
.

Where RADKuniversity is the name of the project, univ is the name of the database, student is the name of the table, 005801234 is the primary key value (in this case may be student_id and json is the format that tells the content the web service is returning by default, it can be json and xml by now when GET returns one record and json only when GET returns all the records). Future implementations will support returning query_string and Object.
In the sample, it will return a Json string with the data from the database.
json format:

{"Table": {"httpStatus":"200","primary_key": "val1","key1": "value1","key2": "value2"}}

or in xml format:

<tables>
  <httpStatus value="200"/>
  <table primary_key="val1" key1="value1" key2="value2" />
 </tables>

where Table is the name of the class corresponding to the table table, httpStatus is the correpsondent number to the successful execution of the method, ke1...key are the names of the corresponding columns and val1 ... val are the values read from the table table.

For example

{"Student": {"httpStatus":"200","student_id": "005802615","name": "Edison Lascano","address": "2199 McLaughlin Ave"}}
<students>
  <httpStatus value="200"/>
  <student student_id="005802615" name="Edison Lascano" address="McLaughlin" />
 </students>

When the web service does not find the record, it will return some response similar to the following:

{"Student",{"httpStatus":"404","Exception:"java.lang.NullPointerException"}}

where "HTTP Status 404" means that the web service was not able to find the current record and "java.lang.NullPointerException" represents the Exception thrown by calling the session beans that process the request.

(Finally, the web client will parse it and write it on the web page).
Other use of the GET method is returning all the records from a table (no pagination is done in the current version)

http://sample.com/myapplication/database/mytables/  
 e.g. 
   http://sample.com/RADKUniversity/RestStudent/students/
.

{"students": [
	{"student_id":"5802615", "name":"Edison Lascano", "address":"McLaughlin"},
	{"student_id":"5802618", "name":"Melody Lascano", "address":"2199 McLaughlin Ave"},
	{"student_id":"5802619", "name":"Caty Lascano", "address":"2199 McLaughlin Ave"},
	{"student_id":"5802620", "name":"Edisito /\" Ã'aÃ'o & #!@$^&*()_+ ", "address":"One Washington Square"},
	{"student_id":"5802621", "name":"Melody", "address":"USA"},
	{"student_id":"5802623", "name":"Edisito", "address":"One Washington Square"},
	{"student_id":"5802627", "name":"Edisito", "address":"One Washington Square"},
	{"student_id":"5802631", "name":"Edisito", "address":"One Washington Square"},
	{"student_id":"58026299", "name":"pepito", "address":"quito"}
  ]
}

POST

The POST method is used to create a new record in the database table, it will receive the data (QUERY_STRING in the body: non visible on the URL) from the correspondent inputs in the web form and parse it before create the record in the database. (Simple conversion of hexadecimal %XX is processed)

http://sample.com/myapplication/RestMytable/mytable/   e.g. http://sample.com/RADKuniversity/RestStudent/student/
.
The data will be passed in form of QUERY_STRING

key1=val1&key2=val2&key3=val3    e.g.   student_id=005802624&name=Edisito&address=One+Washington+Square

If the record is successfully created, then the web service will return text/html:

201 <br/> success Creating table: id<br/> <a href="http://localhost:8080/myapplication/RestMytable/table/{id}/xml">http://localhost:8080/myaaplication/RestMytable/mytable/{id}/xml</a><p/><A HREF="javascript:history.go(-1)">Go back</A>   e.g.
   201 <br/> success Creating student: 23<br/> <a href="http://localhost:8080/WebRestfulTests/RestStudent/student/23/xml">http://localhost:8080/WebRestfulTests/RestStudent/student/23/xml</a><p/><A HREF="javascript:history.go(-1)">Go back</A>

If the record already exists with the same primary key, the Web Service may return a message like the following:

Error Creating student: 23 
nested exception is: java.rmi.ServerException: RemoteException occurred in server thread; nested exception is: java.rmi.RemoteException: null; nested exception is: javax.persistence.EntityExistsException: Exception Description: Cannot persist detached object [entities.Student[studentId=23]]. Class> entities.Student Primary Key> [23]
Try again

PUT

The PUT method is used to update a record in the database table, it will receive the data in a hidden input field called content to read the QUERY_STRING and parse it.

http://sample.com/myapplication/RestMytable/mytable/  e.g. http://sample.com/RADKproject1/RestStudent/student/
.

If the record is successfully updated, then the web service will return:

201 <br/> success Creating table: id<br/> <a href="http://localhost:8080/myapplication/RestMytable/table/{id}/xml">http://localhost:8080/myapplication/RestMytable/table/{id}/xml</a><p/><A HREF="javascript:history.go(-1)">Go back</A>   
e.g.
   201 <br/> success Creating student: 24<br/> <a href="http://localhost:8080/WebRestfulTests/RestStudent/student24/xml">http://localhost:8080/WebRestfulTests/RestStudent/student24/xml</a><p/><A HREF="javascript:history.go(-1)">Go back</A>

otherwise:
it will send a message like:

Error Creating student: 1
<br/>null<p/>
<A HREF="javascript:history.go(-1)">Try again</A>

or like:

Error Creating student: 20
<br/>nested exception is: java.rmi.ServerException: RemoteException occurred in server thread; nested exception is: 
	java.rmi.RemoteException: null; nested exception is: 
	javax.persistence.EntityExistsException: 
Exception Description: Cannot persist detached object [entities.Student[studentId=20]]. 
Class> entities.Student Primary Key> [20]<p/>
<A HREF="javascript:history.go(-1)">Try again</A>

DELETE

Using the URI 

http://sample.com/myapplication/RestMytable/mytable/{myId} e.g. http://sample.com/RADKUniversity/PostStudent/student/123

the method DELETE is used to remove the correspondent record from the database table.

If the record was found and deleted, In the case that the record is successfully removed, the method will return:

{"Student": {"httpStatus":"200"}}

in the case that the method is not able to remove it, it will return the HTTP Status 404, accompanied with the correspondent exception content.

{"Student",{"httpStatus":"404","Exception:"javax.ejb.EJBException: nested except
ion is: java.rmi.ServerException: RemoteException occurred in server thread; nested exception is:
        java.rmi.RemoteException: null; nested exception is:
        java.lang.IllegalArgumentException: Object: null is not a known entity type."}}

where "HTTP Status 404" means there is nothing to erase or some database constraint does not allow to delete the current record and the second element of the json array is the content of the Exception in case of there is some other reason for this action to fail.

RADK Project

There are some ways to test RESTful web swervices

  • cUrl
  • FireFox REST plugin
  • JavaScript
  • jsp

Here some curl samples with an actual web service and database to test.

C:\Users\elascano>curl -X GET http://localhost:8080/WebRestfulTests/RestStudent/
student/0058026234/json
{"Student",{"httpStatus":"404","Exception:"java.lang.NullPointerException"}}

C:\Users\elascano>curl -X GET http://localhost:8080/WebRestfulTests/RestStudent/
student/005802615/json
{"Student",{"httpStatus":"404","Exception:"java.lang.RuntimeException: javax.nam
ing.NameNotFoundException: sessionbeans.StudentFacadeRemote#sessionbeans.Student
FacadeRemote not found"}}

C:\Users\elascano>curl -X GET http://localhost:8080/WebRestfulTests/RestStudent/
student/005802615/json
{"Student": {"httpStatus":"200","student_id": "005802615","name": "Edison Lascan
o","address": "2199 McLaughlin Ave"}}

C:\Users\elascano>curl -X DELETE http://localhost:8080/WebRestfulTests/RestStude
nt/student/005802624
{"Student": {"httpStatus":"200"}}

C:\Users\elascano>curl -X DELETE http://localhost:8080/WebRestfulTests/RestStude
nt/student/005802624
{"Student",{"httpStatus":"404","Exception:"javax.ejb.EJBException: nested except
ion is: java.rmi.ServerException: RemoteException occurred in server thread; nes
ted exception is:
        java.rmi.RemoteException: null; nested exception is:
        java.lang.IllegalArgumentException: Object: null is not a known entity t
ype."}}

C:\Users\elascano>curl -X POST http://localhost:8080/WebRestfulTests/RestStudent
/ -d "student_id=005802631&name=Edisito&address=One+Washington+Square"
{"Student",{"httpStatus":"200","baseUri":"http://localhost:8080/WebRestfulTests/
RestStudent/","content":"student_id=005802631&name=Edisito&address=One+Washingto
n+Square"}}

C:\Users\elascano>curl -X POST http://localhost:8080/WebRestfulTests/RestStudent
/ -d "student_id=005802631&name=Edisito&address=One+Washington+Square"
{"Student",{"httpStatus":"400","Exception":"javax.ejb.EJBException: nested excep
tion is: java.rmi.ServerException: RemoteException occurred in server thread; ne
sted exception is:
        java.rmi.RemoteException: null; nested exception is:
        javax.persistence.EntityExistsException:
Exception Description: Cannot persist detached object [entities.Student[studentI
d=5802631]].
Class> entities.Student Primary Key> [5802631]"}}

List of HTTP responses that can be returned by the RESTful Web Services:

  • Successful Codes (2XX):
    • 200 OK
    • 201 Created
    • 202 Accepted
    • 204 No Content
  • Redirection Codes (3XX):
    • 301 Moved Permanently
    • 304 Not Modified
  • Client Error (4xx)
    • 400 Bad Request
    • 401 Unauthorized
    • 403 Forbidden
    • 404 Not Found
    • 405 Method Not Allowed
  • Server Errors (5xx)
    • 500 Internal Server Error
  • e.g. of uses:
    • 400 for garbage on the Url
    • 500 for run out memory
    • 401 for deletion not allowed
    • 404 we dont have nothing to erase...