Hello again everyone, welcome to module two lesson one of the Web Services course. In this lesson, we'll be talking about the basic parts of a JAX-RS service. We'll apply some of the resource method imitations. We'll use explicit media types in JAX-RS and we'll take a look at marshaling. So JAX-RS is a Java core API which means it's included in the standard language and it's designed to make it easy to develop rest applications. It's a series of annotations and interfaces that standardize the implementation of restful web services in Java. And the main items that are a part of it include resource classes, sub-resource classes, resource methods, sub-resource methods and sub-resource locators. So root resources or resource classes are just Java classes that are annotated with the at path annotation. The only other requirement is that they have one or more methods that are also annotated with the path annotation or that have request method designators. The resource methods are just normal Java methods, but they include a method designator annotation corresponding to one of the HTTP methods. The @Path annotation itself is an annotation that allows you to expose a resource using a Java class. So it actually takes in an argument of a string and that's the name of the resource that you want to expose. So if we wanted to add a slash example resource to the end of coursera.com, we could make a JAX-RS, Java class annotated with @Path that passed in the argument for the path of /example. Inside of that resource class we would include some resource methods and they're going to include request method designators, which are annotations and they correspond to the HTTP methods they use the same name. So they mapped the HTTP method that that resource should take in or that resource method should take in to the Java method itself. In the actual implementation of that method is up to the Java developer. So JAX-RS includes a set of annotations for this that are exactly the name of the HTTP methods. So we've got @get annotation, @post annotation, @put annotation and @delete annotation, and the annotation just maps the HTTP method to the Java method. The implementation is actually up to the developer. So if you decide, you just want to break the rules, you can actually include one of these annotations on a Java method that doesn't do what the HTTP method reveals that it should be doing. So let's review some of the HTTP methods. Get is used to access data, the resource method designator annotation for it is just at get in Java. Post is used to create new data, its sanitation is exactly the same as well, it's @Post. Delete is used to remove data. And put is used to modify existing data in the server. So once it already exists in the server, you want to modify it changed the name of something etc, you'll use a put. So now let's look at a concrete example in code now. So we've got a resource class here, example resource and it's a resource class because it has the @path annotation and it has some resource methods. The @path annotation argument is /example, so this is this resource class is going to correspond with the /example resource in the UR. It's got two resource methods, one of them is @get method called Hello World that just returns a string of hello world. And the other is actually a sub-resource method because it includes its own path annotation and that path is going to be appended onto the end of example. So the path to the resource for more hello world is actually the domain /examples / more. And the only difference here, it's also a get method it's just going to return hello, hello, hello world. So we can take a look at this and curl to test these endpoints. Since the servers running on a local machine, we'll use local host to access it and then the project name. So you see we'll curl HTTP/local host/rest-ws-example, which is just the name of the project. And then /example, that's the name of the resource we exposed and you'll see we didn't actually have to use that -xflag because get is the default HTTP method for curl. And you can see on the second line of this command prompt here, it did return hello world. And then we'll run another command to test the sub-resource method, so we'll do a curl and this time we'll add slash more to the end of the URL. And you'll see this time we actually get hello, hello, hello world. So the @Consumes annotation and the @Produces annotation, specify the media type that a request method should take in or output. They can be applied to the class and all the resource methods will use those media types or they can be applied at the method level. And each method or class can have multiple of these annotations and the most appropriate one depending on the request coming in will be used. So consumes is for the incoming request and produces is for the outgoing response. Both of them take an argument of a string just like the path does, luckily you don't actually have to put in the string yourself. You can use this built in media type class which has many static fields to get the value of the strings. So if you want to use application JSON for your media type, you'll actually just use this media type class.application_JSON inside of the consumes and produces annotation. Marshaling is a fancy computer science term that just refers to the process of taking an object in whatever language and turning it into a string. It's kind of like serialization and the opposite is just called unmarshaling, it's just the process of taking the string back into an object. Behind the scenes, JAX-RS is going to perform marshaling for us based on the media type that we specify the entity mappers are going to perform that marshaling. So there's two types, we've got the MessageBodyReader and the MessageBodyWriter. The MessageBodyReader reads the HTTP request and creates a Java object out of it. The MessageBodyWriter takes our Java object that we return in the resource method and turns it into the response entity. So if we want to input data into our resource methods, we can use path parameters, query parameters or we can send them into the request body. If we want to use path parameters, we have to use the path parameter annotation. If we want to use query parameters, we have to use the query parameter annotation. And with the request body, you actually just add a parameter to the method and it'll be implied that it's coming from the request body. So here's an example with all three, we've got an input resource class with the path/input. It's got three resource methods, one of them is a sub resource method called path example and you can see in its path annotation that's the syntax for defining a path variable there. You use curly braces and then a variable name inside and then if you look at the parameters of the method, you'll see we've got string arg and before it, it includes the path parameter annotation. And inside of it it's got an optional element value that we're setting to a string arg, and that's just the corresponding name between the Java variable and the path variable and it must be included. So in that resource method, we're actually just returning the input value. Then we've got a get method that's taking in query programs. You see the query problems look kind of similar, they also have that optional element that corresponds with the Java variable name except when we go to use this resource method, you'll see the difference. We use a question mark at the end of the URL instead of a sub-resource. And in this example we're taking in plain text and that consumes and we're producing JSON. And so we're actually returning a student object which you'll see JAX-RS is going to marshal for us behind the scenes. And then we've got a post method at the end, it's going to take in a student, you see it doesn't have an annotation. This one's going to come from the request body implicitly and then it's going to set that student's attendance to true and then return the student and it takes in JSON and outputs JSON. So in our first curl example, we're going to send a post to the resource method with the path parameter. And so you can see we did the name of the resource at the end of the URI there, and then also added the sub-resource for the path parameter. And you'll see we've got this percent 20 there, that's actually just an escape character for a space since we can't include spaces there. And it returns hello world, then we've got another example using the get method, notice at the end of this URI, we don't have a sub-resource at the end. We have a question mark and then we're setting first name equal to John and the last name equal to Doe. And that's how query parameters work in the URI and you can see this one's actually returning JSON that's given away by the curly braces and the output there. And for the final example, we're going to do a post to the resource method that's taking in an object from the request body. We have to set in the header, the content type to application JSON. And then we'll use this /d flag to actually put an entity into our request. And so we'll write up JSON and we'll have to use an escape character for some of the inner strings but we're just going to make a JSON object there with the first name of John and the last name of Doe. And you'll see the method once it's done returns a JSON object that has the attended class today set to true.
