Skip to content
BranchesTags

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
.idea
.idea
 
 
src/main/java/lk/kaushalya
src/main/java/lk/kaushalya
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 

Repository files navigation

J2EE-JAX-RS (Java API for RESTful Web Services)

JAX-RS හැඳින්වීම (Introduction to JAX-RS)

JAX-RS යනු RESTful වෙබ් සේවා නිර්මාණය කිරීම සඳහා වන Java API එකකි. REST (Representational State Transfer) යනු වෙබ් සේවා නිර්මාණය කිරීම සඳහා වන ගෘහ නිර්මාණ ශිල්පීය මූලධර්ම සමූහයකි. JAX-RS මගින් මෙම මූලධර්ම මත පදනම්ව, Java annotations ব্যবহার කරමින්, පහසුවෙන් වෙබ් සේවා නිර්මාණය කිරීමට සහ පරිභෝජනය කිරීමට හැකියාව ලබා දේ.

JAX-RS හි වාසි:

  • සරල බව: Annotations භාවිතය නිසා කේතය සරල සහ කියවීමට පහසු වේ.
  • තාක්ෂණයෙන් ස්වාධීන වීම: HTTP protocol එක මත පදනම් වන නිසා, ඕනෑම තාක්ෂණයකින් (JavaScript, Python, etc.) මෙම සේවාවන් පරිභෝජනය කළ හැකිය.
  • Scalability: RESTful සේවාවන් stateless වන නිසා, විශාල පරිශීලකයන් පිරිසකට සේවා සැපයීම සඳහා පහසුවෙන් පරිමාණය කළ හැකිය.

JAX-RS Life Cycle (ජීවන චක්‍රය)

JAX-RS යෙදුමක ජීවන චක්‍රය සරල පියවර කිහිපයකින් සමන්විත වේ:

  1. Request (ඉල්ලීම): Client කෙනෙකු HTTP request එකක් (GET, POST, etc.) යවයි.
  2. Matching (ගැලපීම): JAX-RS runtime එක, request එකේ URL සහ HTTP method එකට ගැලපෙන Java method එකක් (resource method) සොයා ගනී.
  3. Instantiation (උදාහරණයක් නිර්මාණය කිරීම): ගැලපෙන resource class එකේ instance එකක් නිර්මාණය කරයි. (Default වශයෙන්, සෑම request එකකටම නව instance එකක් නිර්මාණය වේ).
  4. Injection (ඇතුළත් කිරීම): Request එකේ ඇති දත්ත (@PathParam, @QueryParam, etc. annotations හරහා) resource method එකේ parameters වලට inject කරයි.
  5. Method Invocation (ක්‍රමය ක්‍රියාත්මක කිරීම): Inject කරන ලද දත්ත සමඟ resource method එක ක්‍රියාත්මක කරයි.
  6. Response (ප්‍රතිචාරය): Method එක මගින් return කරන ලද Java object එක, JAX-RS runtime එක මගින් HTTP response එකක් බවට පරිවර්තනය කර (e.g., JSON, XML), client වෙත යවයි.

JAX-RS Annotations (විවරණ)

JAX-RS හිදී, annotations මගින් සාමාන්‍ය Java class එකක් වෙබ් සම්පතක් (web resource) බවට පත් කරයි.

  • @Path: Resource class එකට හෝ method එකට පිවිසිය යුතු URL පථය නිර්වචනය කරයි.
  • @GET, @POST, @PUT, @DELETE, @PATCH, @HEAD, @OPTIONS: HTTP request වර්ගය නියම කරයි.
  • @Produces: Resource method එක මගින් ආපසු ලබා දෙන දත්ත වර්ගය (MIME type) නියම කරයි (e.g., application/json, application/xml).
  • @Consumes: Resource method එකට ලබාගත හැකි දත්ත වර්ගය නියම කරයි.
  • @PathParam: URL පථයේ කොටසක් විචල්‍යයක් ලෙස ලබා ගැනීමට භාවිතා කරයි.
  • @QueryParam: URL එකේ query string එකෙන් (e.g., ?name=John) පරාමිතීන් ලබා ගැනීමට භාවිතා කරයි.
  • @HeaderParam: HTTP header එකෙන් අගයන් ලබා ගැනීමට භාවිතා කරයි.
  • @FormParam: HTML form එකකින් submit කරන ලද දත්ත ලබා ගැනීමට භාවිතා කරයි.
  • @CookieParam: Cookie වලින් අගයන් ලබා ගැනීමට භාවිතා කරයි.
  • @Context: HTTP-specific තොරතුරු (e.g., HttpServletRequest, UriInfo) inject කිරීමට භාවිතා කරයි.

HTTP Methods (HTTP ක්‍රම)

RESTful සේවාවන්හිදී, සම්පත් (resources) මත සිදුකරන ක්‍රියාවන් (operations) නිරූපණය කිරීමට HTTP methods භාවිතා කරයි.

1. @GET

  • කාර්යය: සම්පතක් (resource) ලබා ගැනීම.
  • විස්තරය: දත්ත සමුදායෙන් දත්ත ලබා ගැනීමට, ගොනුවක් ලබා ගැනීමට වැනි දේ සඳහා භාවිතා කරයි. මෙය ආරක්ෂිත සහ idempotent (එකම request එක කිහිප වරක් යැවූ විට ප්‍රතිඵලය වෙනස් නොවීම) ක්‍රමයකි.

උදාහරණය:

@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public User getUserById(@PathParam("id") int id) {
    // ... id එකට අදාළ user ව ලබාගන්නා කේතය ...
    return user;
}

2. @POST

  • කාර්යය: නව සම්පතක් නිර්මාණය කිරීම.
  • විස්තරය: නව පරිශීලකයෙකු ලියාපදිංචි කිරීම, නව ලිපියක් පළ කිරීම වැනි දේ සඳහා භාවිතා කරයි. මෙය idempotent නොවේ (එකම request එක කිහිප වරක් යැවූ විට නව සම්පත් කිහිපයක් නිර්මාණය විය හැක).

උදාහරණය:

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response createUser(User user) {
    // ... user ව දත්ත සමුදායට ඇතුළත් කරන කේතය ...
    return Response.status(Response.Status.CREATED).entity(user).build();
}

3. @PUT

  • කාර්යය: පවතින සම්පතක් යාවත්කාලීන කිරීම හෝ ප්‍රතිස්ථාපනය කිරීම.
  • විස්තරය: සම්පතක් සම්පූර්ණයෙන්ම යාවත්කාලීන කිරීමට භාවිතා කරයි. Client විසින් සම්පතේ සම්පූර්ණ නිරූපණය (representation) යැවිය යුතුය. මෙය idempotent වේ.

උදාහරණය:

@PUT
@Path("/{id}")
@Consumes(MediaType.APPLICATION_JSON)
public Response updateUser(@PathParam("id") int id, User updatedUser) {
    // ... id එකට අදාළ user ගේ තොරතුරු updatedUser හි ඇති තොරතුරු වලින් යාවත්කාලීන කිරීම ...
    return Response.ok().build();
}

4. @DELETE

  • කාර්යය: සම්පතක් ඉවත් කිරීම.
  • විස්තරය: නිශ්චිත සම්පතක් සර්වරයෙන් ඉවත් කිරීමට භාවිතා කරයි. මෙය idempotent වේ.

උදාහරණය:

@DELETE
@Path("/{id}")
public Response deleteUser(@PathParam("id") int id) {
    // ... id එකට අදාළ user ව දත්ත සමුදායෙන් ඉවත් කිරීම ...
    return Response.noContent().build();
}

5. @PATCH

  • කාර්යය: සම්පතක කොටසක් පමණක් යාවත්කාලීන කිරීම.
  • විස්තරය: PUT මෙන් නොව, සම්පතේ වෙනස් කළ යුතු කොටස පමණක් යැවීමට භාවිතා කරයි. (e.g., පරිශීලකයාගේ දුරකථන අංකය පමණක් වෙනස් කිරීම).

6. @HEAD

  • කාර්යය: GET request එකකට සමාන නමුත්, response body එක නොමැතිව, headers පමණක් ලබා ගැනීම.
  • විස්තරය: සම්පතක් බාගත කිරීමට පෙර එහි විශාලත්වය (Content-Length) හෝ වෙනස් වූ දිනය (Last-Modified) වැනි තොරතුරු දැනගැනීමට භාවිතා කරයි.

7. @OPTIONS

  • කාර්යය: සම්පතක් සඳහා සහාය දක්වන HTTP methods මොනවාදැයි දැන ගැනීම.
  • විස්තරය: CORS (Cross-Origin Resource Sharing) වැනි යාන්ත්‍රණ වලදී බහුලව භාවිතා වේ.

Data Handling (දත්ත හැසිරවීම)

Parameters යැවීම සහ ලබා ගැනීම

1. @PathParam

URL පථයේ ඇති විචල්‍ය කොටස් ලබා ගැනීමට.

  • URL: http://example.com/users/123
  • කේතය:
@GET
@Path("/users/{userId}")
public Response getUser(@PathParam("userId") int userId) {
    // userId = 123
    return Response.ok("Requested user ID: " + userId).build();
}

2. @QueryParam

URL එකේ query string එකෙන් දත්ත ලබා ගැනීමට.

  • URL: http://example.com/users?orderBy=name&limit=10
  • කේතය:
@GET
@Path("/users")
public Response getUsers(@QueryParam("orderBy") String orderBy, @QueryParam("limit") int limit) {
    // orderBy = "name", limit = 10
    return Response.ok("Ordering by " + orderBy + " with limit " + limit).build();
}

3. @FormParam

HTML form එකකින් application/x-www-form-urlencoded ලෙස එවන දත්ත ලබා ගැනීමට.

  • HTML Form: 
    <form action="/users" method="post">
    <input type="text" name="name" />
    <input type="text" name="email" />
    <button type="submit">Create</button>
</form>
  • කේතය:
@POST
@Path("/users")
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response createUser(@FormParam("name") String name, @FormParam("email") String email) {
    // ... name සහ email භාවිතා කර user නිර්මාණය කිරීම ...
    return Response.status(Response.Status.CREATED).build();
}

4. Request Body (JSON/XML)

@POST හෝ @PUT වැනි request වලදී, request body එකේ එවන JSON/XML දත්ත, Java object (POJO) එකකට ස්වයංක්‍රීයව පරිවර්තනය කරගත හැක. මේ සඳහා jackson හෝ moxy වැනි library එකක් අවශ්‍ය වේ.

  • JSON: { "name": "John Doe", "age": 30 }
  • POJO (User.java): 
    public class User {
    private String name;
    private int age;
    // getters and setters
}
  • කේතය:
@POST
@Path("/users")
@Consumes(MediaType.APPLICATION_JSON)
public Response createUser(User user) {
    // JAX-RS runtime එක මගින් JSON එක User object එකක් බවට පත් කරයි.
    // user.getName() -> "John Doe"
    return Response.ok().build();
}

File Uploads (ගොනු උඩුගත කිරීම)

ගොනු උඩුගත කිරීම සඳහා multipart/form-data භාවිතා කරයි. ഇതിനായി jersey-multipart වැනි අමතර library එකක් අවශ්‍ය වේ.

කේතය:

@POST
@Path("/upload")
@Consumes(MediaType.MULTIPART_FORM_DATA)
public Response uploadFile(
    @FormDataParam("file") InputStream uploadedInputStream,
    @FormDataParam("file") FormDataContentDisposition fileDetail) {

    String uploadedFileLocation = "d:/upload/" + fileDetail.getFileName();

    // ගොනුව සර්වරයේ save කිරීම
    writeToFile(uploadedInputStream, uploadedFileLocation);

    String output = "File uploaded to : " + uploadedFileLocation;

    return Response.status(200).entity(output).build();
}

Response Handling (ප්‍රතිචාර හැසිරවීම)

Resource method එකකින් Response object එකක් return කිරීමෙන්, HTTP response එක (status code, headers, body) සම්පූර්ණයෙන්ම පාලනය කළ හැකිය.

@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public Response getUser(@PathParam("id") int id) {
    User user = findUserById(id);

    if (user == null) {
        // User හමු නොවූ විට 404 Not Found status එක යැවීම
        return Response.status(Response.Status.NOT_FOUND).entity("User not found").build();
    }

    // User හමු වූ විට 200 OK status එක සහ user object එක යැවීම
    return Response.ok(user).build();
    // return Response.status(Response.Status.OK).entity(user).build(); ලෙසද ලිවිය හැක.
}

පොදු Status Codes:

  • 200 OK: සාර්ථකයි.
  • 201 Created: සම්පතක් සාර්ථකව නිර්මාණය කරන ලදී.
  • 204 No Content: සාර්ථකයි, නමුත් response body එකක් නොමැත (e.g., DELETE).
  • 400 Bad Request: Client ගේ request එකේ දෝෂයකි (e.g., වැරදි දත්ත ආකෘතිය).
  • 401 Unauthorized: Authentication අවශ්‍යයි.
  • 403 Forbidden: Authentication සාර්ථක වුවත්, එම ක්‍රියාවට අවසර නැත.
  • 404 Not Found: ඉල්ලූ සම්පත සොයාගත නොහැක.
  • 500 Internal Server Error: සර්වරයේ දෝෂයකි.

Error Handling (දෝෂ හැසිරවීම)

JAX-RS හි දෝෂ හැසිරවීම සඳහා ExceptionMapper භාවිතා කළ හැක. මෙය මගින් නිශ්චිත exception එකක් ඇති වූ විට, එයට අදාළව custom HTTP response එකක් සකස් කර යැවිය හැක.

උදාහරණය: UserNotFoundException එකක් ඇති වූ විට 404 Not Found ලෙස ප්‍රතිචාර දැක්වීම.

Exception Class:

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

Exception Mapper:

@Provider
public class UserNotFoundExceptionMapper implements ExceptionMapper<UserNotFoundException> {

    @Override
    public Response toResponse(UserNotFoundException exception) {
        return Response.status(Response.Status.NOT_FOUND)
                       .entity(exception.getMessage())
                       .type(MediaType.TEXT_PLAIN)
                       .build();
    }
}

Resource Method:

@GET
@Path("/{id}")
public User getUser(@PathParam("id") int id) {
    User user = findUserById(id);
    if (user == null) {
        throw new UserNotFoundException("User with ID " + id + " not found.");
    }
    return user;
}

Security (ආරක්ෂාව)

JAX-RS සේවාවන්හි ආරක්ෂාව සඳහා විවිධ ක්‍රම භාවිතා කළ හැක.

  1. Authentication (සත්‍යාපනය): පරිශීලකයා කවුදැයි හඳුනා ගැනීම.

    • Basic Authentication: Username සහ Password, Base64 encode කර Authorization header එකේ යැවීම.
    • Token-Based Authentication (e.g., JWT - JSON Web Tokens): Login වූ පසු, සර්වරයෙන් token එකක් ලබා දෙන අතර, client විසින් සෑම request එකකම එම token එක Authorization header එකේ (Bearer <token>) යැවිය යුතුය.

  2. Authorization (බලය පැවරීම): පරිශීලකයාට යම් ක්‍රියාවක් කිරීමට අවසර තිබේදැයි පරීක්ෂා කිරීම.

    • JAX-RS Security Context: @Context SecurityContext inject කරගැනීමෙන්, පරිශීලකයාගේ නම (securityContext.getUserPrincipal().getName()) සහ role එක (securityContext.isUserInRole("ADMIN")) පරීක්ෂා කළ හැක.

උදාහරණය (Role-based access):

import javax.annotation.security.RolesAllowed;

@GET
@Path("/admin")
@RolesAllowed("ADMIN") // "ADMIN" role එක ඇති අයට පමණක් පිවිසිය හැක
public Response getAdminData() {
    // ...
    return Response.ok("This is admin data.").build();
}
  1. HTTPS: Client සහ Server අතර දත්ත සම්ප්‍රේෂණයේදී, දත්ත encrypt කිරීම සඳහා SSL/TLS භාවිතා කිරීම අනිවාර්ය වේ.

මෙම සටහන මගින් JAX-RS හි මූලික සහ වැදගත් සංකල්ප සියල්ලම, සිංහලෙන් සහ උදාහරණ සහිතව ආවරණය කර ඇත.

About

A comprehensive guide and reference for Java EE JAX-RS (RESTful Web Services) built with Jersey and Maven. Includes detailed code examples, annotations, lifecycle concepts, request handling, file uploads, exception mapping, and security implementations explained clearly in Sinhala.

Topics

javajava-eejava-ee-applicationjax-rsjax-rs-apijax-rs-clientjax-rs-httpjax-rs-serverrest-apirestful-web-services

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages