bundles/org.eclipse.rap.doc/guide/articles/resources.html - rap/org.eclipse.rap.tools - Git at Google

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
   <meta name="copyright" content="Copyright (c) 2007, 2019 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   <title>Static Resources</title>
   <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
 </head>
 <body>

   <h1>Static Resources and Downloads</h1>

   <h2>Registering Static Resources</h2>

   <p>
     Every RAP application can host it's own static resources, like documents, scripts, images,
     or CSS-files. These can then be used
   </p>
   <ul>
     <li><a href="application-configuration.html#entrypointconfig">for favicons and splash-screen</a>...</li>
     <li><a href="markup.html#img">for images</a> and <a href="markup.html#link">links</a> in markup...</li>
     <li><a href="web-embedding.html">within of a browser widget</a>...</li>
     <li><a href="client.html#jsloader">with the JavaScriptLoader</a>...</li>
     <li><a href="navigation.html#launcher">with the URLLauncher</a>...</li>
     <li><a href="custom-widget.html#native">for JavaScript-based custom widgets</a>...</li>
   </ul>
   <p>
     It is <i>not</i> necessary to register images used by
     <a href="theming.html">CSS theming</a>.
   </p>
   <p>
     There are multiple ways to register a resource, with the main difference beeing the time
     and place the registration happens.
   </p>

   <ul>
     <li>
       The <em><a href="application-configuration.html">ApplicationConfiguration</a></em> is a good place
       to register resources that you know will be required throughout your applications lifecycle.
       Example:
       <pre class="lang-java">
 application.addResource( "foo/icon.png", new ResourceLoader() {
   @Override
   public InputStream getResourceAsStream( String resourceName ) throws IOException {
     return this.getClass().getClassLoader().getResourceAsStream( "resources/icon.png" );
   }
 } );</pre>
     </li>
     <li>
       For
       <a href="branding.html">workbench applications</a>,
       the
       <em><a href="../reference/extension-points/org_eclipse_rap_ui_resources.html">org.eclipse.rap.ui.resources</a></em>
       extension point and
       <em>IResource</em><!-- link not possible, not in API reference -->
       interface provide the same service as the application configuration above. One notable difference
       is that the extension also makes it simple for other bundles other than the RAP application
       itself to register resources.
       Also, any registered JavaScript file will automatically
       be executed when the web client is loaded. The
       <em><a href="../reference/api/org/eclipse/rap/rwt/client/service/ClientFileLoader.html">ClientFileLoader</a></em>
       is not required in that case. Example for plugin.xml:
     <pre class="lang-xml">
 &lt;extension point="org.eclipse.rap.ui.resources"&gt;
   &lt;resource class="my.project.resources.IconResource"&gt;
   &lt;/resource&gt;
 &lt;/extension&gt;</pre>
     </li>
     <li>
       The most universal approach is using the
       <em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html">ResourceManager</a></em>
       directly,
       which allows
       <em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html#register-java.lang.String-java.io.InputStream-">registering</a></em>
       and
       <em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html#unregister-java.lang.String-">de-registering</a></em>
       any resource at any time.
       <pre class="lang-java">
 ResourceManager resourceManager = RWT.getResourceManager();
 if( !resourceManager.isRegistered( "foo/icon.png" ) ) {
   InputStream inputStream = this.getClass().getClassLoader().getResourceAsStream( "resources/icon.png" );
   try {
     resourceManager.register( resourceName, inputStream );
   } finally {
     inputStream.close();
   }
 }</pre>
     </li>
   </ul>

   <p>
     <strong>Important:</strong> To use the resource on the client (e.g. in a browser widget or the <em>JavaScriptLoader</em>),
     is it necessary to know it's public URL from the clients point of view.
     (The favicon in the application configuration/branding is an
     exception, it can use the path given during registration).
     This information is in all cases provided by the <em>ResourceManager</em>:
   </p>
 <pre class="lang-java">
 String src = RWT.getResourceManager().getLocation( "foo/icon.png" );
 </pre>

   <h2>Service Handler and Downloads</h2>
   <p>
     If you want to provide downloads in your RAP application, you can use a service
     handler instead of static resources.
     Below is an example of a very basic downloads service handler.
   </p>
 <pre class="lang-java">
 public class DownloadServiceHandler implements ServiceHandler {

   public void service( HttpServletRequest request, HttpServletResponse response )
     throws IOException, ServletException
   {
     // Which file to download?
     String fileName = request.getParameter( "filename" );
     // Get the file content
     byte[] download = MyDataStore.getByteArrayData( fileName );
     // Send the file in the response
     response.setContentType( "application/octet-stream" );
     response.setContentLength( download.length );
     String contentDisposition = "attachment; filename=\"" + fileName + "\"";
     response.setHeader( "Content-Disposition", contentDisposition );
     response.getOutputStream().write( download );
   }
 }
 </pre>
   <p>
     The request has a parameter "filename" which indicates which content
     (either static or dynamically generated) should be sent to the client.
     The <code>MyDataStore</code>-line is a placeholder for whatever
     code is required to provide the content.
     In our example the content is retrieved as <code>byte[]</code>,
     but InputStreams and Readers can be easily accommodated as well.
   </p>
   <p>
     The service handler has to be registered, like static resources, once <i>per application</i>.
     The best place to do this is (depending on your <a href="application-setup.html">application setup</a>)
     either the <a href="application-configuration.html">Application Configuration</a> or
     <em><a href="../reference/extension-points/org_eclipse_rap_ui_serviceHandler.html">
     org.eclipse.rap.ui.serviceHandler</a></em> extension. If need be it can also be done at runtime:
   </p>
   <pre class="lang-java">
 ServiceManager manager = RWT.getServiceManager();
 ServiceHandler handler = new DownloadServiceHandler();
 manager.registerServiceHandler( "downloadServiceHandler", handler );
 </pre>
   <p>
     The URL for the download link can be generated as follows:
   </p>
 <pre class="lang-java">
 private String createDownloadUrl( String filename ) {
   StringBuilder url = new StringBuilder();
   url.append( RWT.getServiceManager().getServiceHandlerUrl( "downloadServiceHandler" ) );
   url.append( '&amp;' ).append( "filename" ).append( '=' ).append( filename );
   return url.toString();
 }</pre>
 <p>
   The link can either be embedded using <a href="markup.html#link">markup</a>, or
   opened programmatically with the <a href="navigation.html#launcher">URLLauncher</a>.
   The application can <strong>not</strong> control whether certain file types are opened
   in a browser popup/tab/window, or in a "save-as" dialog. This is completely up to the browser.
   However, a markup hyperlink usually has a native context menu with a "save-as" entry.
 </p>
 </body>
 </html>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta name="copyright" content="Copyright (c) 2007, 2019 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
	<title>Static Resources</title>
	<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
	</head>
	<body>

	<h1>Static Resources and Downloads</h1>

	<h2>Registering Static Resources</h2>

	<p>
	Every RAP application can host it's own static resources, like documents, scripts, images,
	or CSS-files. These can then be used
	</p>
	<ul>
	<li><a href="application-configuration.html#entrypointconfig">for favicons and splash-screen</a>...</li>
	<li><a href="markup.html#img">for images</a> and <a href="markup.html#link">links</a> in markup...</li>
	<li><a href="web-embedding.html">within of a browser widget</a>...</li>
	<li><a href="client.html#jsloader">with the JavaScriptLoader</a>...</li>
	<li><a href="navigation.html#launcher">with the URLLauncher</a>...</li>
	<li><a href="custom-widget.html#native">for JavaScript-based custom widgets</a>...</li>
	</ul>
	<p>
	It is <i>not</i> necessary to register images used by
	<a href="theming.html">CSS theming</a>.
	</p>
	<p>
	There are multiple ways to register a resource, with the main difference beeing the time
	and place the registration happens.
	</p>

	<ul>
	<li>
	The <em><a href="application-configuration.html">ApplicationConfiguration</a></em> is a good place
	to register resources that you know will be required throughout your applications lifecycle.
	Example:
	<pre class="lang-java">
	application.addResource( "foo/icon.png", new ResourceLoader() {
	@Override
	public InputStream getResourceAsStream( String resourceName ) throws IOException {
	return this.getClass().getClassLoader().getResourceAsStream( "resources/icon.png" );
	}
	} );</pre>
	</li>
	<li>
	For
	<a href="branding.html">workbench applications</a>,
	the
	<em><a href="../reference/extension-points/org_eclipse_rap_ui_resources.html">org.eclipse.rap.ui.resources</a></em>
	extension point and
	<em>IResource</em><!-- link not possible, not in API reference -->
	interface provide the same service as the application configuration above. One notable difference
	is that the extension also makes it simple for other bundles other than the RAP application
	itself to register resources.
	Also, any registered JavaScript file will automatically
	be executed when the web client is loaded. The
	<em><a href="../reference/api/org/eclipse/rap/rwt/client/service/ClientFileLoader.html">ClientFileLoader</a></em>
	is not required in that case. Example for plugin.xml:
	<pre class="lang-xml">
	<extension point="org.eclipse.rap.ui.resources">
	<resource class="my.project.resources.IconResource">
	</resource>
	</extension></pre>
	</li>
	<li>
	The most universal approach is using the
	<em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html">ResourceManager</a></em>
	directly,
	which allows
	<em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html#register-java.lang.String-java.io.InputStream-">registering</a></em>
	and
	<em><a href="../reference/api/org/eclipse/rap/rwt/service/ResourceManager.html#unregister-java.lang.String-">de-registering</a></em>
	any resource at any time.
	<pre class="lang-java">
	ResourceManager resourceManager = RWT.getResourceManager();
	if( !resourceManager.isRegistered( "foo/icon.png" ) ) {
	InputStream inputStream = this.getClass().getClassLoader().getResourceAsStream( "resources/icon.png" );
	try {
	resourceManager.register( resourceName, inputStream );
	} finally {
	inputStream.close();
	}
	}</pre>
	</li>
	</ul>

	<p>
	<strong>Important:</strong> To use the resource on the client (e.g. in a browser widget or the <em>JavaScriptLoader</em>),
	is it necessary to know it's public URL from the clients point of view.
	(The favicon in the application configuration/branding is an
	exception, it can use the path given during registration).
	This information is in all cases provided by the <em>ResourceManager</em>:
	</p>
	<pre class="lang-java">
	String src = RWT.getResourceManager().getLocation( "foo/icon.png" );
	</pre>

	<h2>Service Handler and Downloads</h2>
	<p>
	If you want to provide downloads in your RAP application, you can use a service
	handler instead of static resources.
	Below is an example of a very basic downloads service handler.
	</p>
	<pre class="lang-java">
	public class DownloadServiceHandler implements ServiceHandler {

	public void service( HttpServletRequest request, HttpServletResponse response )
	throws IOException, ServletException
	{
	// Which file to download?
	String fileName = request.getParameter( "filename" );
	// Get the file content
	byte[] download = MyDataStore.getByteArrayData( fileName );
	// Send the file in the response
	response.setContentType( "application/octet-stream" );
	response.setContentLength( download.length );
	String contentDisposition = "attachment; filename=\"" + fileName + "\"";
	response.setHeader( "Content-Disposition", contentDisposition );
	response.getOutputStream().write( download );
	}
	}
	</pre>
	<p>
	The request has a parameter "filename" which indicates which content
	(either static or dynamically generated) should be sent to the client.
	The <code>MyDataStore</code>-line is a placeholder for whatever
	code is required to provide the content.
	In our example the content is retrieved as <code>byte[]</code>,
	but InputStreams and Readers can be easily accommodated as well.
	</p>
	<p>
	The service handler has to be registered, like static resources, once <i>per application</i>.
	The best place to do this is (depending on your <a href="application-setup.html">application setup</a>)
	either the <a href="application-configuration.html">Application Configuration</a> or
	<em><a href="../reference/extension-points/org_eclipse_rap_ui_serviceHandler.html">
	org.eclipse.rap.ui.serviceHandler</a></em> extension. If need be it can also be done at runtime:
	</p>
	<pre class="lang-java">
	ServiceManager manager = RWT.getServiceManager();
	ServiceHandler handler = new DownloadServiceHandler();
	manager.registerServiceHandler( "downloadServiceHandler", handler );
	</pre>
	<p>
	The URL for the download link can be generated as follows:
	</p>
	<pre class="lang-java">
	private String createDownloadUrl( String filename ) {
	StringBuilder url = new StringBuilder();
	url.append( RWT.getServiceManager().getServiceHandlerUrl( "downloadServiceHandler" ) );
	url.append( '&' ).append( "filename" ).append( '=' ).append( filename );
	return url.toString();
	}</pre>
	<p>
	The link can either be embedded using <a href="markup.html#link">markup</a>, or
	opened programmatically with the <a href="navigation.html#launcher">URLLauncher</a>.
	The application can <strong>not</strong> control whether certain file types are opened
	in a browser popup/tab/window, or in a "save-as" dialog. This is completely up to the browser.
	However, a markup hyperlink usually has a native context menu with a "save-as" entry.
	</p>
	</body>
	</html>