javaeetutorial
  1. javaeetutorial
  2. JAVAEETUTORIAL-252

Incorrect instructions for Section 29.3.1, Creating A Simple RESTful Web Service

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 7.0.3
    • Fix Version/s: 7.0.4
    • Component/s: doc
    • Labels:
      None

      Description

      There are several issues that need to be address with regard to the documentation surrounding the simplest of the 3 JAX-RS examples.

      The sentence that precedes 29.3.1.1 needs to be modified to say something to the effect that the prebuilt example is similar but not identical to the example that one can build from the archetype. There should also be links to new sections for running that prebuilt example with NetBeans IDE and Maven from the command line.

      There needs to be a step 0 that says "Ensure that you have installed the tutorial archetypes as described in Section 2.7.1, Installing the Tutorial Archetypes.

      Step 1d needs to be changed from "... and click Next." to "... and click Finish."

      Step 1e needs to be deleted.

      In step 2, delete "and the exception".

      In step 2, move the Note so that it follows the code example.

      In step 3, change "hello project" to "HelloWorldApplication project" and change "Build" to "Run".

      In step 4, change the URL from "http://localhost:8080/hello" to "http://localhost:8080/HelloWorldApplication/HelloWorldApplication".

      Add a new section - 29.3.1.2, To Run the hello Example with NetBeans IDE.

      Add a new section - 29.3.1.3, To Run the hello Example with Maven.

      Make sure the instructions match the prebuilt example. For example, the URL to open would be http://localhost:8080/hello/helloworld.

        Activity

        Hide
        jendrock added a comment -

        I think this is the only example in the tutorial that users actually create. First Cup does the same thing but the example that is supplied matches (exactly) the example that users end up with after they follow the step-by-step instructions. The JAX-RS hello example is close, but definitely not identical to the resultant example users will build in this case. This is a different animal than we are used to.

        I am surprised that no users have asked how to run hello, either by using Maven or NetBeans IDE. If hello matched the end result that the users built, no NB instructions would be needed. Would they ask how to run with Maven? Not to use Maven to build the example from the archetype but to run the prebuilt example.

        Maybe I'm all wet. Maybe what is needed is to make the examples the same and simply say that the example is provided as a reference, as you said.

        Show
        jendrock added a comment - I think this is the only example in the tutorial that users actually create. First Cup does the same thing but the example that is supplied matches (exactly) the example that users end up with after they follow the step-by-step instructions. The JAX-RS hello example is close, but definitely not identical to the resultant example users will build in this case. This is a different animal than we are used to. I am surprised that no users have asked how to run hello, either by using Maven or NetBeans IDE. If hello matched the end result that the users built, no NB instructions would be needed. Would they ask how to run with Maven? Not to use Maven to build the example from the archetype but to run the prebuilt example. Maybe I'm all wet. Maybe what is needed is to make the examples the same and simply say that the example is provided as a reference, as you said.
        Hide
        Ian Evans added a comment -

        We've never had separate sections on running the pre-built example we documented in our step-by-step instructions before. The assumption has always been that the pre-built version is more of a reference for a working version of what you end up with rather than an example that is documented separately.

        I'm fine putting in two new sections on running hello, but this is somewhat different than our previous practices.

        Show
        Ian Evans added a comment - We've never had separate sections on running the pre-built example we documented in our step-by-step instructions before. The assumption has always been that the pre-built version is more of a reference for a working version of what you end up with rather than an example that is documented separately. I'm fine putting in two new sections on running hello, but this is somewhat different than our previous practices.
        Hide
        jendrock added a comment -

        So, the jaxrs/hello example that is is the workspace serves what purpose? Is it supposed to be run? If so, how? I just thought that if we provide an example, especially one that is different from the one that is built from the archetype, we would also have instructions for running it. In fact, that is how the whole issue came about. I was asked if we had a very simple JAX-RS example. I said we did. And then I was asked for directions for running it from the command line. That we did not have.

        Show
        jendrock added a comment - So, the jaxrs/hello example that is is the workspace serves what purpose? Is it supposed to be run? If so, how? I just thought that if we provide an example, especially one that is different from the one that is built from the archetype, we would also have instructions for running it. In fact, that is how the whole issue came about. I was asked if we had a very simple JAX-RS example. I said we did. And then I was asked for directions for running it from the command line. That we did not have.
        Hide
        Ian Evans added a comment -

        Fixed the instructions, except for the new sub-sections on running in NetBeans/with Maven.

        Show
        Ian Evans added a comment - Fixed the instructions, except for the new sub-sections on running in NetBeans/with Maven.
        Hide
        Ian Evans added a comment -

        There is no need for separate "To Run the Example..." sub-sections because this step-by-step is only for NetBeans users. We don't document how to create new examples based on the archetypes on the command-line, although it is definitely possible to do so.

        Show
        Ian Evans added a comment - There is no need for separate "To Run the Example..." sub-sections because this step-by-step is only for NetBeans users. We don't document how to create new examples based on the archetypes on the command-line, although it is definitely possible to do so.

          People

          • Assignee:
            Ian Evans
            Reporter:
            jendrock
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: