Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 245 insertions, 0 deletions

diff --git a/documentation/application/application-resources.asciidoc b/documentation/application/application-resources.asciidoc
new file mode 100644
index 0000000000..b5f5db91f2
--- /dev/null
+++ b/documentation/application/application-resources.asciidoc
@@ -0,0 +1,245 @@
+---
+title: Images and Other Resources
+order: 5
+layout: page
+---
+
+[[application.resources]]
+= Images and Other Resources
+
+Web applications can display various __resources__, such as images, other
+embedded content, or downloadable files, that the browser has to load from the
+server. Image resources are typically displayed with the [classname]#Image#
+component or as component icons. Flash animations can be displayed with
+[classname]#Flash#, embedded browser frames with [classname]#BrowserFrame#, and
+other content with the [classname]#Embedded# component, as described in
+<<dummy/../../../framework/components/components-embedded#components.embedded,"Embedded
+Resources">>. Downloadable files are usually provided by clicking a
+[classname]#Link#.
+
+There are several ways to how such resources can be provided by the web server.
+Static resources can be provided without having to ask for them from the
+application. For dynamic resources, the user application must be able to create
+them dynamically. The resource request interfaces in Vaadin allow applications
+to both refer to static resources as well as dynamically create them. The
+dynamic creation includes the [classname]#StreamResource# class and the
+[interfacename]#RequestHandler# described in
+<<dummy/../../../framework/advanced/advanced-requesthandler#advanced.requesthandler,"Request
+Handlers">>.
+
+Vaadin also provides low-level facilities for retrieving the URI and other
+parameters of a HTTP request. We will first look into how applications can
+provide various kinds of resources and then look into low-level interfaces for
+handling URIs and parameters to provide resources and functionalities.
+
+Notice that using request handlers to create "pages" is not normally meaningful
+in Vaadin or in AJAX applications generally. Please see
+<<dummy/../../../framework/architecture/architecture-technology#architecture.technology.ajax,"AJAX">>
+for a detailed explanation.
+
+[[application.resources.api]]
+== Resource Interfaces and Classes
+
+The resource classes in Vaadin are grouped under two interfaces: a generic
+[classname]#Resource# interface and a more specific
+[classname]#ConnectorResource# interface for resources provided by the servlet.
+
+[[figure.resource.classdiagram]]
+.Resource Interface and Class Diagram
+image::img/resource_classdiagram-hi.png[]
+
+
+[[application.resources.file]]
+== File Resources
+
+File resources are files stored anywhere in the file system. As such, they can
+not be retrieved by a regular URL from the server, but need to be requested
+through the Vaadin servlet. The use of file resources is typically necessary for
+persistent user data that is not packaged in the web application, which would
+not be persistent over redeployments.
+
+A file object that can be accessed as a file resource is defined with the
+standard [classname]#java.io.File# class. You can create the file either with an
+absolute or relative path, but the base path of the relative path depends on the
+installation of the web server. For example, with Apache Tomcat, the default
+current directory would be the installation path of Tomcat.
+
+In the following example, we provide an image resource from a file stored in the
+web application. Notice that the image is stored under the [filename]#WEB-INF#
+folder, which is a special folder that is never accessible using an URL, unlike
+the other folders of a web application. This is a security solution - another
+would be to store the resource elsewhere in the file system.
+
+
+[source, java]
+----
+// Find the application directory
+String basepath = VaadinService.getCurrent()
+                  .getBaseDirectory().getAbsolutePath();
+
+// Image as a file resource
+FileResource resource = new FileResource(new File(basepath +
+                        "/WEB-INF/images/image.png"));
+
+// Show the image in the application
+Image image = new Image("Image from file", resource);
+        
+// Let the user view the file in browser or download it
+Link link = new Link("Link to the image file", resource);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#application.resources.fileresource[on-line example, window="_blank"].
+
+The result, as well as the folder structure where the file is stored under a
+regular Eclipse Vaadin project, is shown in
+<<figure.application.resources.file>>.
+
+[[figure.application.resources.file]]
+.File Resource
+image::img/resource-fileresource.png[]
+
+
+[[application.resources.class]]
+== Class Loader Resources
+
+The [classname]#ClassResource# allows resources to be loaded from the class path
+using Java Class Loader. Normally, the relevant class path entry is the
+[filename]#WEB-INF/classes# folder under the web application, where the Java
+compilation should compile the Java classes and copy other files from the source
+tree.
+
+The one-line example below loads an image resource from the application package
+and displays it in an [classname]#Image# component.
+
+
+[source, java]
+----
+layout.addComponent(new Image(null,
+        new ClassResource("smiley.jpg")));
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#application.resources.classresource[on-line example, window="_blank"].
+
+
+[[application.resources.theme]]
+== Theme Resources
+
+Theme resources of [classname]#ThemeResource# class are files, typically images,
+included in a theme. A theme is located with the path
+[filename]#VAADIN/themes/themename# in a web application. The name of a theme
+resource is given as the parameter for the constructor, with a path relative to
+the theme folder.
+
+
+[source, java]
+----
+// A theme resource in the current theme ("mytheme")
+// Located in: VAADIN/themes/mytheme/img/themeimage.png
+ThemeResource resource = new ThemeResource("img/themeimage.png");
+
+// Use the resource
+Image image = new Image("My Theme Image", resource);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#application.resources.themeresource[on-line example, window="_blank"].
+
+The result is shown in <<figure.application.resources.theme>>, also illustrating
+the folder structure for the theme resource file in an Eclipse project.
+
+[[figure.application.resources.theme]]
+.Theme Resources
+image::img/resource-themeimage.png[]
+
+To use theme resources, you must set the theme for the UI. See
+<<dummy/../../../framework/themes/themes-overview.asciidoc#themes.overview,"Themes">>
+for more information regarding themes.
+
+
+[[application.resources.stream]]
+== Stream Resources
+
+Stream resources allow creating dynamic resource content. Charts are typical
+examples of dynamic images. To define a stream resource, you need to implement
+the [classname]#StreamResource.StreamSource# interface and its
+[methodname]#getStream()# method. The method needs to return an
+[classname]#InputStream# from which the stream can be read.
+
+The following example demonstrates the creation of a simple image in PNG image
+format.
+
+
+[source, java]
+----
+import java.awt.image.*;
+
+public class MyImageSource
+             implements StreamResource.StreamSource {
+    ByteArrayOutputStream imagebuffer = null;
+    int reloads = 0;
+    
+    /* We need to implement this method that returns
+     * the resource as a stream. */
+    public InputStream getStream () {
+        /* Create an image and draw something on it. */
+        BufferedImage image = new BufferedImage (200, 200,
+                               BufferedImage.TYPE_INT_RGB);
+        Graphics drawable = image.getGraphics();
+        drawable.setColor(Color.lightGray);
+        drawable.fillRect(0,0,200,200);
+        drawable.setColor(Color.yellow);
+        drawable.fillOval(25,25,150,150);
+        drawable.setColor(Color.blue);
+        drawable.drawRect(0,0,199,199);
+        drawable.setColor(Color.black);
+        drawable.drawString("Reloads="+reloads, 75, 100);
+        reloads++;
+
+        try {
+            /* Write the image to a buffer. */
+            imagebuffer = new ByteArrayOutputStream();
+            ImageIO.write(image, "png", imagebuffer);
+            
+            /* Return a stream from the buffer. */
+            return new ByteArrayInputStream(
+                         imagebuffer.toByteArray());
+        } catch (IOException e) {
+            return null;
+        }
+    }
+}
+----
+
+The content of the generated image is dynamic, as it updates the reloads counter
+with every call. The [classname]#ImageIO#. [methodname]#write()# method writes
+the image to an output stream, while we had to return an input stream, so we
+stored the image contents to a temporary buffer.
+
+Below we display the image with the [classname]#Image# component.
+
+
+[source, java]
+----
+// Create an instance of our stream source.
+StreamResource.StreamSource imagesource = new MyImageSource ();
+	
+// Create a resource that uses the stream source and give it a name.
+// The constructor will automatically register the resource in
+// the application.
+StreamResource resource =
+        new StreamResource(imagesource, "myimage.png");
+	
+// Create an image component that gets its contents
+// from the resource.
+layout.addComponent(new Image("Image title", resource));
+----
+
+The resulting image is shown in <<figure.application.resource.stream>>.
+
+[[figure.application.resource.stream]]
+.A Stream Resource
+image::img/application_streamresource.png[]
+
+Another way to create dynamic content is a request handler, described in
+<<dummy/../../../framework/advanced/advanced-requesthandler#advanced.requesthandler,"Request
+Handlers">>.
+
+
+
+