From 578587b3122be372d931a2eb37dbe1265eb38d45 Mon Sep 17 00:00:00 2001 From: John Calcote Date: Tue, 29 Aug 2017 10:50:01 -0600 Subject: [PATCH] Grammar and spelling in getting-started and user-guide xml files. --- docs/src/main/docbook/getting-started.xml | 178 +++++++++++----------- docs/src/main/docbook/user-guide.xml | 16 +- 2 files changed, 97 insertions(+), 97 deletions(-) diff --git a/docs/src/main/docbook/getting-started.xml b/docs/src/main/docbook/getting-started.xml index 5f15b27e36..eb8c636f65 100644 --- a/docs/src/main/docbook/getting-started.xml +++ b/docs/src/main/docbook/getting-started.xml @@ -63,10 +63,10 @@ Creating a New Project from Maven Archetype - Jersey project is built using &maven.link; software project build and management tool. All modules produced as - part of Jersey project build are pushed to the &maven.central.repo.link;. Therefore it is very convenient to work - with Jersey for any Maven-based project as all the released (non-SNAPSHOT) Jersey dependencies are readily - available without a need to configure a special maven repository to consume the Jersey modules. + A Jersey project is built using the &maven.link; software project build and management tool. All modules produced as + part of the Jersey project build are pushed to the &maven.central.repo.link;. Therefore it is very convenient to work + with Jersey for any Maven-based project, as all the released (non-SNAPSHOT) Jersey dependencies are readily + available without the need to configure a special maven repository to consume the Jersey modules. @@ -83,8 +83,8 @@ - Since starting from a Maven project is the most convenient way for working with Jersey, let's now have a look - at this approach. We will now create a new Jersey project that runs on top of a &grizzly.link; container. We will + Since starting from a Maven project is the most convenient way to work with Jersey, let's now consider + this approach. We'll create a new Jersey project that runs in a &grizzly.link; container. We'll use a Jersey-provided maven archetype. To create the project, execute the following Maven command in the directory where the new project should reside: @@ -94,14 +94,14 @@ -DarchetypeVersion=&version; Feel free to adjust the groupId, package and/or artifactId - of your new project. Alternatively, you can change it by updating the new project pom.xml once it gets generated. + elements of your new project. Alternatively, you can change it by updating the new project pom.xml once it gets generated.
Exploring the Newly Created Project - Once the project generation from a Jersey maven archetype is successfully finished, you should see the new + Once project generation from a Jersey maven archetype has successfully completed, you should see the new simple-service project directory created in your current location. The directory contains a standard Maven project structure: @@ -114,10 +114,10 @@ Project test sources are located under src/test/java. - There are 2 classes in the project source directory in the com.example package. - The Main class is responsible for bootstrapping the Grizzly container as well as configuring + There are 2 classes in the project source directory within the com.example package. + The Main class is responsible for bootstrapping the Grizzly container, as well as configuring and deploying the project's JAX-RS application to the container. Another class in the same package - is MyResource class, that contains implementation of a simple JAX-RS resource. + is the MyResource class, that contains an implementation of a simple JAX-RS resource. It looks like this: package com.example; @@ -147,18 +147,18 @@ public class MyResource { } A JAX-RS resource is an annotated POJO that provides so-called resource methods that - are able to handle HTTP requests for URI paths that the resource is bound to. See + are able to handle HTTP requests for the URI paths the resource is bound to. See for a complete guide to JAX-RS resources. In our case, the resource - exposes a single resource method that is able to handle HTTP &lit.http.GET; requests, is bound to - /myresource URI path and can produce responses with response message content represented - in "text/plain" media type. In this version, the resource returns the same + exposes a single resource method that handles HTTP &lit.http.GET; requests, is bound to the + /myresource URI path, and can produce responses with response message content represented + in the "text/plain" media type. In this version, the resource returns the same "Got it!" response to all client requests. The last piece of code that has been generated in this skeleton project is a MyResourceTest unit test class that is located in the same com.example package as the - MyResource class, however, this unit test class is placed into the maven project test source - directory src/test/java (certain code comments and JUnit imports have been excluded for brevity): + MyResource class. However, this unit test class is located in the maven project test source + directory, src/test/java (certain code comments and JUnit imports have been excluded for brevity): package com.example; @@ -198,20 +198,20 @@ public class MyResourceTest { } } - In this unit test, a Grizzly container is first started and server application is deployed in the + In this unit test, a Grizzly container is started and the server application is deployed in the test setUp() method by a static call to Main.startServer(). - Next, a JAX-RS client components are created in the same test set-up method. First a new JAX-RS client - instance c is built and then a JAX-RS web target component pointing to the context root of our - application deployed at http://localhost:8080/myapp/ (a value of - Main.BASE_URI constant) is stored into a target field of the unit test class. + Next, JAX-RS client components are created in the same test set-up method. First, a new JAX-RS client + instance, c, is built and then a JAX-RS web target component pointing to the context root of our + application, deployed at http://localhost:8080/myapp/ (a value of + Main.BASE_URI constant), is stored into a target field of the unit test class. This field is then used in the actual unit test method (testGetIt()). - In the testGetIt() method a fluent JAX-RS Client API is used to connect to and send - a HTTP &lit.http.GET; request to the MyResource JAX-RS resource class listening on + In the testGetIt() method, a fluent JAX-RS Client API is used to connect to and send + an HTTP &lit.http.GET; request to the MyResource JAX-RS resource class listening on the /myresource URI. As part of the same fluent JAX-RS API method invocation chain, a response is - read as a Java String type. On the second line in the test method, the response content string - returned from the server is compared with the expected phrase in the test assertion. To learn more about using + read as a Java String. On the second line in the test method, the response content string + returned from the server is compared with the expected phrase in the test assertion. To learn more about using the JAX-RS Client API, please see the chapter.
@@ -219,12 +219,12 @@ public class MyResourceTest {
Running the Project - Now that we have seen the content of the project, let's try to test-run it. To do this, we need to invoke following + Now that we have seen the content of the project, let's try to test-run it. To do this, we need to invoke the following command on the command line: mvn clean test - This will compile the project and run the project unit tests. We should see a similar output that informs about a + This will compile the project and run the project unit tests. We should see a similar output informing us of a successful build once the build is finished: Results : @@ -244,7 +244,7 @@ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 mvn exec:java - The application starts and you should soon see the following notification in your console: + The application starts and soon afterward you should see this notification on your console: May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.NetworkListener start INFO: Started listener bound to [localhost:8080] @@ -253,23 +253,23 @@ INFO: [HttpServer] Started. Jersey app started with WADL available at http://localhost:8080/myapp/application.wadl Hit enter to stop it... - This informs you that the application has been started and it's WADL descriptor is available at - http://localhost:8080/myapp/application.wadl URL. You can retrieve the WADL content by - executing a curl http://localhost:8080/myapp/application.wadl command in your console - or by typing the WADL URL into your favorite browser. You should get back an XML document in describing - your deployed RESTful application in a WADL format. To learn more about working with WADL, check the + This informs you that the application has been started and its WADL descriptor is available at + http://localhost:8080/myapp/application.wadl. You can retrieve the WADL content by + executing curl http://localhost:8080/myapp/application.wadl at your console prompt, + or by typing the WADL URL into your favorite browser. You should get back an XML document describing + your deployed RESTful application in a WADL format. To learn more about working with WADL, check out the chapter. The last thing we should try before concluding this section is to see if we can communicate with our - resource deployed at /myresource path. We can again either type the resource URL + resource deployed at /myresource. Once again, we can either type the resource URL in the browser or we can use curl: $ curl http://localhost:8080/myapp/myresource Got it! - As we can see, the curl command returned with the Got it! message that - was sent by our resource. We can also ask curl to provide more information about the response, + As you can see, the curl command returned the Got it! message + sent by our resource. We can also ask curl to provide more information about the response, for example we can let it display all response headers by using the -i switch: curl -i http://localhost:8080/myapp/myresource @@ -280,15 +280,15 @@ Content-Length: 7 Got it! - Here we see the whole content of the response message that our Jersey/JAX-RS application returned, including all + Here we see the entire content of the response message that our Jersey/JAX-RS application returned, including all the HTTP headers. Notice the Content-Type: text/plain header that was derived from the value of &jaxrs.Produces; annotation attached to the MyResource class. - In case you want to see even more details about the communication between our curl client - and our resource running on Jersey in a Grizzly I/O container, feel free to try other various options and switches - that curl provides. For example, this last command will make curl output - a lot of additional information about the whole communication: + If you'd like to see even more details about the communication between our curl client + and our resource running on Jersey, in a Grizzly I/O container, feel free to try other curl + options and switches. For example, this command will make curl display + a lot of additional information about the entire communication session:
Creating a JavaEE Web Application - To create a Web Application that can be packaged as WAR and deployed in a Servlet container follow a similar process - to the one described in . - In addition to the Grizzly-based archetype, Jersey provides also a Maven archetype for creating web application - skeletons. To create the new web application skeleton project, execute the following Maven command in the directory + To create a Web Application that can be packaged as a .war file and deployed in a Servlet container, follow a process + similar to the one described in . + In addition to the Grizzly-based archetype, Jersey also provides a Maven archetype for creating web application + skeletons. To create a new web application skeleton project, execute the following Maven command in the directory where the new project should reside: mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-webapp \ @@ -327,14 +327,14 @@ Got it!* Closing connection #0]]> -DarchetypeVersion=&version; As with the Grizzly based project, feel free to adjust the groupId, package - and/or artifactId of your new web application project. Alternatively, you can change it by updating - the new project &lit.pom.xml; once it gets generated. + and/or artifactId elements of your new web application project. Alternatively, you can change it by updating + the new project's &lit.pom.xml; once it's generated. - Once the project generation from a Jersey maven archetype is successfully finished, you should see the new - simple-service-webapp project directory created in your current location. The directory contains - a standard Maven project structure, similar to the simple-service project content we have seen - earlier, except it is extended with an additional web application specific content: + When the Jersey maven archetype project has been successfully generated, you should see the new + simple-service-webapp project created within the current directory. The directory contains + a standard Maven project structure, similar to the simple-service project content we saw + earlier, except that it's extended with additional web application specific content: @@ -346,19 +346,19 @@ Got it!* Closing connection #0]]> Project web application files are located under src/main/webapp. - The project contains the same MyResouce JAX-RS resource class. It does not contain any unit tests - as well as it does not contain a Main class that was used to setup Grizzly container in the + The project contains the same MyResouce JAX-RS resource class. However, it doesn't contain any unit tests + and it doesn't contain the Main class used to setup the Grizzly container in the previous project. Instead, it contains the standard Java EE web application web.xml deployment descriptor under src/main/webapp/WEB-INF. The last component in the project is an index.jsp page that serves as a client for the - MyResource resource class that is packaged and deployed with the application. + MyResource resource class packaged and deployed with the application. - To compile and package the application into a WAR, invoke the following maven command in your console: + To compile and package the application into a .war file, invoke the following maven command at your console: mvn clean package - A successful build output will produce an output similar to the one below: + A successful build will produce output similar to the following: Results : @@ -381,12 +381,12 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 [INFO] Final Memory: 17M/490M [INFO] ------------------------------------------------------------------------ - Now you are ready to take the packaged WAR (located under ./target/simple-service-webapp.war) - and deploy it to a Servlet container of your choice. + Now you are ready to deploy the packaged .war file (located under ./target/simple-service-webapp.war) + to a Servlet container of your choice. To deploy a Jersey application, you will need a Servlet container that supports Servlet 2.5 or later. - For full set of advanced features (such as JAX-RS 2.0 Async Support) you will need a Servlet 3.0 or later + For the full set of advanced features (such as JAX-RS 2.0 Async Support) you will need a Servlet 3.0 (or later) compliant container. @@ -396,8 +396,8 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
Creating a Web Application that can be deployed on Heroku - To create a Web Application that can be either packaged as WAR and deployed in a Servlet container or that can be - pushed and deployed on &heroku.link; the process is very similar to the one described in . + To create a Web Application that can be either packaged as a .war file, and deployed to a Servlet container, or that can be + pushed to the Internet and deployed on &heroku.link; the process is very similar to the one described in . To create the new web application skeleton project, execute the following Maven command in the directory where the new project should reside: @@ -406,13 +406,13 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 -DgroupId=com.example -DartifactId=simple-heroku-webapp -Dpackage=com.example \ -DarchetypeVersion=&version; - Adjust the groupId, package and/or artifactId of your new web - application project to your needs or, alternatively, you can change it by updating the new project &lit.pom.xml; once it - gets generated. + Adjust the groupId, package and/or artifactId elements of your new web + application project to your needs or, alternatively, you can change it by updating the new project &lit.pom.xml; once it's been + generated. - Once the project generation from a Jersey maven archetype is successfully finished, you should see the new - simple-heroku-webapp project directory created in your current location. The directory contains + Once project generation from a Jersey maven archetype has successfully completed, you should see the new + simple-heroku-webapp project directory created within your current directory. The directory contains a standard Maven project structure: @@ -425,22 +425,22 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 Project web application files are located under src/main/webapp. Project test-sources (based on &jersey.test.JerseyTest;) are located under src/test/java. Heroku system properties (OpenJDK version) are defined in system.properties. - Lists of the process types in an application for Heroku is in Procfile. + Lists of the process types in an application for Heroku are in Procfile. The project contains one JAX-RS resource class, MyResouce, and one resource method which returns - simple text message. To make sure the resource is properly tested there is also a end-to-end test-case + a simple text message. To make sure the resource is properly tested, there is also an end-to-end test-case in MyResourceTest (the test is based on &jersey.test.JerseyTest; from our ). - Similarly to simple-service-webapp, the project contains the standard Java EE web application - web.xml deployment descriptor under src/main/webapp/WEB-INF since the goal is to + Similar to the simple-service-webapp project, this project contains the standard Java EE web application + web.xml deployment descriptor under src/main/webapp/WEB-INF, since the goal is to deploy the application in a Servlet container (the application will run in Jetty on Heroku). - To compile and package the application into a WAR, invoke the following maven command in your console: + To compile and package the application into a .war file, invoke the following maven command at your console: mvn clean package - A successful build output will produce an output similar to the one below: + A successful build will produce output similar to the following: Results : @@ -490,14 +490,14 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 [INFO] Final Memory: 20M/246M [INFO] ------------------------------------------------------------------------ - Now that you know everything went as expected you are ready to: + Now that you know everything went as expected, you are ready to: make some changes in your project, - take the packaged WAR (located under ./target/simple-service-webapp.war) and deploy it to a + deploy the .war file (located under ./target/simple-service-webapp.war) to a Servlet container of your choice, or @@ -507,8 +507,8 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 - If you want to make some changes to your application you can run the application locally by simply running - mvn clean package jetty:run (which starts the embedded Jetty server) or by + If you want to make some changes to your application you can run it locally by simply executing + mvn clean package jetty:run (which starts the embedded Jetty server), or by executing java -cp target/classes:target/dependency/* com.example.heroku.Main (this is how Jetty is started on Heroku). @@ -517,14 +517,14 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
Deploy it on Heroku - We won't go into details how to create an account on &heroku.link; and setup the Heroku tools - on your machine. You can find a lot of information in this article: Getting Started with Java on Heroku. + We won't go into details about how to create an account on &heroku.link; and setup the Heroku tools + on your development machine. You can find a lot of information in this article: Getting Started with Java on Heroku. Instead, we'll take a look at the steps needed after your environment is ready. The first step is to create a Git repository from your project: $ git init - Initialized empty Git repository in /.../simple-heroku-webapp/.git/ + Initialized an empty Git repository in /.../simple-heroku-webapp/.git/ Then, create a &heroku.link; instance and add a remote reference to your Git repository: @@ -535,7 +535,7 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 - The name of the instance is changed in the output to simple-heroku-webapp. Your will be + The name of the instance is changed in the output to simple-heroku-webapp. Yours will be named more like tranquil-basin-4744. @@ -555,7 +555,7 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 create mode 100644 system.properties - Push changes to Heroku: + Push the changes to Heroku: $ git push heroku master Counting objects: 21, done. Delta compression using up to 8 threads. @@ -650,7 +650,7 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 * [new branch] master -> master - Now you can access your application at, for example: http://simple-heroku-webapp.herokuapp.com/myresource + Now you can access your application at (for example): http://simple-heroku-webapp.herokuapp.com/myresource
@@ -658,15 +658,15 @@ Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
Exploring Other Jersey Examples - In the sections above, we have covered an approach how to get dirty with Jersey quickly. Please consult the other + In the sections above, we covered an approach for getting dirty with Jersey quickly. Please consult the other sections of the Jersey User Guide to learn more about Jersey and JAX-RS. - Even though we try our best to cover as much as possible in the User Guide, there is always a chance that you would - not be able to get a full answer to the problem you are solving. In that case, consider diving in our examples that - provide additional tips and hints to the features you may want to use in your projects. + Even though we try our best to cover as much as possible in the User Guide, there is always a chance you'll + not be able to find a complete answer to your specific problem. In that case, consider diving in our examples, which + provide additional tips and hints about features you may wish to use in your projects. - Jersey codebase contains a number of useful examples on how to use various JAX-RS and Jersey features. - Feel free to browse through the code of individual + The Jersey codebase contains a number of useful examples on how to use various JAX-RS and Jersey features. + Feel free to browse through the code of the individual Jersey Examples in the Jersey source repository. For off-line browsing, you can also download a bundle with all the examples from here. diff --git a/docs/src/main/docbook/user-guide.xml b/docs/src/main/docbook/user-guide.xml index 6828ca31e7..f9d5f01dae 100644 --- a/docs/src/main/docbook/user-guide.xml +++ b/docs/src/main/docbook/user-guide.xml @@ -55,17 +55,17 @@ Preface - This is user guide for Jersey &version;. We are trying to keep it up to date as we add new features. - When reading the user guide, please consult also our + This is the user guide for Jersey &version;. We are trying to keep it up to date as we add new features. + When reading the user guide, please also consult our Jersey API documentation as an additional source of information about Jersey features and API. - If you would like to contribute to the guide or have questions on things not covered in our docs, please + If you would like to contribute to the guide, or have questions on things not covered in our docs, please contact us atusers@jersey.java.net. Similarly, in case you spot any errors in the Jersey documentation, please report them by filing a new issue in our Jersey JIRA Issue Tracker - under + under the docs component. Please make sure to specify the version of the Jersey User Guide where the error has been spotted by selecting the proper value for the @@ -75,8 +75,8 @@ Text formatting conventions - First mention of any Jersey and JAX-RS API component in a section links to the API documentation of the - referenced component. Any sub-sequent mentions of the component in the same chapter are rendered using a + The first mention of any Jersey and JAX-RS API component in a section links to the API documentation of the + referenced component. Any subsequent mentions of the component in the same chapter are rendered using a monospaced font. @@ -87,11 +87,11 @@ In some of the code listings, certain lines are too long to be displayed on one line for the available - page width. In such case, the lines that exceed the available page width are broken up into multiple lines + page width. In such cases, the lines that exceed the available page width are broken up into multiple lines using a '\' at the end of each line to indicate that a break has been introduced to - fit the line in the page. For example: + fit the line on the page. For example: This is an overly long line that \