examples/bookstore-webapp/README.MD - third_party/eclipse-ee4j/jersey - Git at Google


            
            [//]: # " Copyright (c) 2015, 2018 Oracle and/or its affiliates. All rights reserved. "

            
            [//]: # " "

            
            [//]: # " Redistribution and use in source and binary forms, with or without "

            
            [//]: # " modification, are permitted provided that the following conditions are met: "

            
            [//]: # " "

            
            [//]: # " 1. Redistributions of source code must retain the above copyright notice, this "

            
            [//]: # "    list of conditions and the following disclaimer. "

            
            [//]: # " 2. Redistributions in binary form must reproduce the above copyright notice, "

            
            [//]: # "    this list of conditions and the following disclaimer in the documentation "

            
            [//]: # "    and/or other materials provided with the distribution. "

            
            [//]: # " "

            
            [//]: # " THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND "

            
            [//]: # " ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED "

            
            [//]: # " WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE "

            
            [//]: # " DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR "

            
            [//]: # " ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES "

            
            [//]: # " (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; "

            
            [//]: # " LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND "

            
            [//]: # " ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT "

            
            [//]: # " (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS "

            
            [//]: # " SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. "

            
            [//]: # " "

            
            [//]: # " SPDX-License-Identifier: BSD-2-Clause "


            Bookstore

            
            =========


            This example demonstrates how to connect JSP pages to resources. The

            
            example is copied from the

            
            [Bookstore](http://stapler.kohsuke.org/getting-started.html) example

            
            presented by the [Stapler](http://stapler.kohsuke.org/) project that

            
            provides a way to staple URIs to Java classes to build RESTful Web

            
            applications such as [Hudson](http://java.net/projects/hudson/).


            A bookstore Web application is presented that is capable of presenting

            
            books, CDs and tracks of CDs.


            Contents

            
            --------


            The example consists of four web resources implemented by the following:


            `org.glassfish.jersey.examples.bookstore.webapp.resource.Bookstore`


            The bookstore resource that returns a list of items, either CDs

            
            or Books. The resource dynamically references a Book or CD resource

            
            using the getItem method that is annotated with Path. The Book and

            
            CD resource both inherit from the Item class and thus the resources

            
            can be managed polymorphically.


            `org.glassfish.jersey.examples.bookstore.webapp.resource.Book`


            The book resource that has a title and an author.


            `org.glassfish.jersey.examples.bookstore.webapp.resource.CD`


            The CD resource that has a title, author and a list of tracks. The

            
            resource dynamically references the Track resource using the

            
            getTrack method that is annotated with Path.


            `org.glassfish.jersey.examples.bookstore.webapp.resource.Track`


            The Tracks resource that has a name and the length of the track.


            The mapping of the URI path space is presented in the following table:


            URI path                            | Resource class   | HTTP methods   | Notes

            
            ----------------------------------- | ---------------- | -------------- | ------------------------------------------------------------------------------

            
            **_/_**                             | Bookstore        | GET            | webapp/resource/Bookstore/index.jsp

            
            **_/count_**                        | Bookstore        | GET            | webapp/resource/Bookstore/count.jsp

            
            **_/time_**                         | Bookstore        | GET            | webapp/resource/Bookstore/time.jsp

            
            **_/items/{itemid}_**               | Book, CD         | GET            | webapp/resource/Book/index.jsp, webapp/resource/CD/index.jsp

            
            **_/items/{itemid}/tracks/{num}_**  | Track            | GET            | webapp/resource/Track/index.jsp


            Running the Example

            
            -------------------


            Bookstore example runs on Glassfish 6.0 application server

            
            ([https://javaee.github.io/glassfish/](https://javaee.github.io/glassfish/)), which can be

            
            run as an embedded container or Jetty.


            If you are working with Jersey GlassFish update center module installed

            
            into your existing GlassFish instance, you will need to follow

            
            instructions at [the module README file](../../README.md) in order to

            
            deploy the example.


            Otherwise, you can run the example using embedded GlassFish as follows:


            Build and deploy the project by executing the following command from the

            
            project directory


            >   mvn clean package embedded-glassfish:run (TODO does not work at the moment)


            or you can run the example using Jetty as follows:


            >   mvn clean package jetty:run


            Go to the URL:


            <http://localhost:8080/bookstore-webapp/>


            #### Test Client Running


            >   mvn test -Djersey.config.test.container.factory=org.glassfish.jersey.test.external.ExternalTestContainerFactory -Djersey.config.test.logging.enable=true -Djersey.config.test.logging.dumpEntity=true -Djersey.config.test.container.port=8080 -Dmaven.test.skip=false


            or


            >   mvn test -Prun-external-tests


            How it works

            
            ------------


            This example shows how to support polymorphism of resources and JSP

            
            pages. Hence it is possible to add another resource, such as a DVD

            
            resource with associated JSP pages, which extends Item without having to

            
            change the logic of Bookstore or the existing JSP pages.


            JSP pages are associated with resource classes. Such JSP pages are

            
            resolved by converting the fully qualified class name of the resource

            
            class into a path and appending last path segment of the request URI

            
            path to that path. For example, when a GET is performed on the URI path

            
            "/" then the path to the JSP page is

            
            "/org/glassfish/jersey/examples/bookstore/webapp/resource/Bookstore/",

            
            and in this case since the last path segment is empty "index.jsp" is

            
            appended to the path. Then the request us forwarded to the JSP page at

            
            that path. Similarly when a GET is performed on the URI path "/count"

            
            then the path to the JSP page is

            
            "//org/glassfish/jersey/examples/bookstore/webapp/resource/Bookstore/count.jsp".


            The JSP variable "it" is set to the instance of Bookstore so that the

            
            index.jsp, or count.jsp, has access to the Bookstore instance as a Java

            
            bean.


            If a resource class inherits from another resource class then it will

            
            automatically inherit the JSPs from the super class.


            A JSP page may also include JSPs using the inheritance mechanism, for

            
            example the index.jsp page associated with the Book resource class

            
            includes a footer.jsp page whose location is specified by the super

            
            class, Item.
	[//]: # " Copyright (c) 2015, 2018 Oracle and/or its affiliates. All rights reserved. "
	[//]: # " "
	[//]: # " Redistribution and use in source and binary forms, with or without "
	[//]: # " modification, are permitted provided that the following conditions are met: "
	[//]: # " "
	[//]: # " 1. Redistributions of source code must retain the above copyright notice, this "
	[//]: # " list of conditions and the following disclaimer. "
	[//]: # " 2. Redistributions in binary form must reproduce the above copyright notice, "
	[//]: # " this list of conditions and the following disclaimer in the documentation "
	[//]: # " and/or other materials provided with the distribution. "
	[//]: # " "
	[//]: # " THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND "
	[//]: # " ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED "
	[//]: # " WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE "
	[//]: # " DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR "
	[//]: # " ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES "
	[//]: # " (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; "
	[//]: # " LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND "
	[//]: # " ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT "
	[//]: # " (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS "
	[//]: # " SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. "
	[//]: # " "
	[//]: # " SPDX-License-Identifier: BSD-2-Clause "

	Bookstore
	=========

	This example demonstrates how to connect JSP pages to resources. The
	example is copied from the
	[Bookstore](http://stapler.kohsuke.org/getting-started.html) example
	presented by the [Stapler](http://stapler.kohsuke.org/) project that
	provides a way to staple URIs to Java classes to build RESTful Web
	applications such as [Hudson](http://java.net/projects/hudson/).

	A bookstore Web application is presented that is capable of presenting
	books, CDs and tracks of CDs.

	Contents
	--------

	The example consists of four web resources implemented by the following:

	`org.glassfish.jersey.examples.bookstore.webapp.resource.Bookstore`

	The bookstore resource that returns a list of items, either CDs
	or Books. The resource dynamically references a Book or CD resource
	using the getItem method that is annotated with Path. The Book and
	CD resource both inherit from the Item class and thus the resources
	can be managed polymorphically.

	`org.glassfish.jersey.examples.bookstore.webapp.resource.Book`

	The book resource that has a title and an author.

	`org.glassfish.jersey.examples.bookstore.webapp.resource.CD`

	The CD resource that has a title, author and a list of tracks. The
	resource dynamically references the Track resource using the
	getTrack method that is annotated with Path.

	`org.glassfish.jersey.examples.bookstore.webapp.resource.Track`

	The Tracks resource that has a name and the length of the track.

	The mapping of the URI path space is presented in the following table:


	URI path \| Resource class \| HTTP methods \| Notes
	----------------------------------- \| ---------------- \| -------------- \| ------------------------------------------------------------------------------
	_/_ \| Bookstore \| GET \| webapp/resource/Bookstore/index.jsp
	_/count_ \| Bookstore \| GET \| webapp/resource/Bookstore/count.jsp
	_/time_ \| Bookstore \| GET \| webapp/resource/Bookstore/time.jsp
	_/items/{itemid}_ \| Book, CD \| GET \| webapp/resource/Book/index.jsp, webapp/resource/CD/index.jsp
	_/items/{itemid}/tracks/{num}_ \| Track \| GET \| webapp/resource/Track/index.jsp

	Running the Example
	-------------------

	Bookstore example runs on Glassfish 6.0 application server
	([https://javaee.github.io/glassfish/](https://javaee.github.io/glassfish/)), which can be
	run as an embedded container or Jetty.

	If you are working with Jersey GlassFish update center module installed
	into your existing GlassFish instance, you will need to follow
	instructions at [the module README file](../../README.md) in order to
	deploy the example.

	Otherwise, you can run the example using embedded GlassFish as follows:

	Build and deploy the project by executing the following command from the
	project directory

	> mvn clean package embedded-glassfish:run (TODO does not work at the moment)

	or you can run the example using Jetty as follows:

	> mvn clean package jetty:run

	Go to the URL:

	<http://localhost:8080/bookstore-webapp/>

	#### Test Client Running

	> mvn test -Djersey.config.test.container.factory=org.glassfish.jersey.test.external.ExternalTestContainerFactory -Djersey.config.test.logging.enable=true -Djersey.config.test.logging.dumpEntity=true -Djersey.config.test.container.port=8080 -Dmaven.test.skip=false

	or

	> mvn test -Prun-external-tests

	How it works
	------------

	This example shows how to support polymorphism of resources and JSP
	pages. Hence it is possible to add another resource, such as a DVD
	resource with associated JSP pages, which extends Item without having to
	change the logic of Bookstore or the existing JSP pages.

	JSP pages are associated with resource classes. Such JSP pages are
	resolved by converting the fully qualified class name of the resource
	class into a path and appending last path segment of the request URI
	path to that path. For example, when a GET is performed on the URI path
	"/" then the path to the JSP page is
	"/org/glassfish/jersey/examples/bookstore/webapp/resource/Bookstore/",
	and in this case since the last path segment is empty "index.jsp" is
	appended to the path. Then the request us forwarded to the JSP page at
	that path. Similarly when a GET is performed on the URI path "/count"
	then the path to the JSP page is
	"//org/glassfish/jersey/examples/bookstore/webapp/resource/Bookstore/count.jsp".

	The JSP variable "it" is set to the instance of Bookstore so that the
	index.jsp, or count.jsp, has access to the Bookstore instance as a Java
	bean.

	If a resource class inherits from another resource class then it will
	automatically inherit the JSPs from the super class.

	A JSP page may also include JSPs using the inheritance mechanism, for
	example the index.jsp page associated with the Book resource class
	includes a footer.jsp page whose location is specified by the super
	class, Item.