diff options
Diffstat (limited to 'documentation/application/application-resources.asciidoc')
| -rw-r--r-- | documentation/application/application-resources.asciidoc | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/documentation/application/application-resources.asciidoc b/documentation/application/application-resources.asciidoc deleted file mode 100644 index b5f5db91f2..0000000000 --- a/documentation/application/application-resources.asciidoc +++ /dev/null @@ -1,245 +0,0 @@ ---- -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">>. - - - - |