<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Upload_Component">
	<title>Upload Component</title>
	<!-- 	<section id="sect-Reference_Guide-Upload_Component-Overview">
		<title>Overview</title>
		<para>
			In this article, you will learn how to:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					configure the Upload service
				</para>
			</listitem>
			<listitem>
				<para>
					add a default upload size limit
				</para>
			</listitem>
			<listitem>
				<para>
					use the Upload component in your application, with a specific upload size limit
				</para>
			</listitem>
			<listitem>
				<para>
					clean the service when the upload finishes
				</para>
			</listitem>
		</itemizedlist>
	</section>  -->
	<section id="sect-Reference_Guide-Upload_Component-Upload_Service">
		<title>Upload Service</title>
		<para>
			The service is defined by the class: <literal>org.exoplatform.upload.UploadService</literal>;
		</para>
		<para>
			This can be configured with the following xml code:
		</para>
		
<programlisting language="xml">&#60;component&#62;
   &#60;type&#62;org.exoplatform.upload.UploadService&#60;/type&#62;
     &#60;init-params&#62;
       &#60;value-param&#62;
        &#60;name&#62;upload.limit.size&#60;/name&#62;
        &#60;description&#62;Maximum size of the file to upload in MB&#60;/description&#62;
        &#60;value&#62;10&#60;/value&#62;
      &#60;/value-param&#62;
    &#60;/init-params&#62;  
  &#60;/component&#62;
</programlisting>
		<para>
			This code allows for a default upload size limit for the service to be configured. The value unit is in MegaBytes.
		</para>
		<para>
			This limit will be used by default by all applications if no application-specific limit is set. Setting a different limit for applications is discussed in a later section.
		</para>
		<para>
			If the value is set to <parameter>0</parameter>, the upload size is unlimited.
		</para>
		<procedure id="proc-Reference_Guide-Upload_Service-How_to_use_the_upload_component">
			<title>How to use the upload component</title>
			<step>
				<para>
					Create an object type <literal>org.exoplatform.webui.form.UIFormUploadInput</literal>.
				</para>
				<para>
					Two constructors are available for this:
				</para>
				
<programlisting language="java">public UIFormUploadInput(String name, String bindingExpression)
</programlisting>
				<para>
					or:
				</para>
				
<programlisting language="java">public UIFormUploadInput(String name, String bindingExpression, int limit)
</programlisting>
				<para>
					This is an example using the second form:
				</para>
				
<programlisting language="java">PortletRequestContext pcontext = (PortletRequestContext)WebuiRequestContext.getCurrentInstance();
PortletPreferences portletPref = pcontext.getRequest().getPreferences();
int limitMB = Integer.parseInt(portletPref.getValue(&#34;uploadFileSizeLimitMB&#34;, &#34;&#34;).trim());
UIFormUploadInput uiInput = new UIFormUploadInput(&#34;upload&#34;, &#34;upload&#34;, limitMB);
</programlisting>
			</step>
			<step>
				<para>
					To obtain the limit from the <literal>xml</literal> configuration, this piece of code can be added to the either <filename>portlet.xml</filename> or <filename>portlet-preferences.xml</filename>:
				</para>
				
<programlisting language="xml">&#60;preference&#62;
  &#60;name&#62;uploadFileSizeLimitMB&#60;/name&#62;
  &#60;value&#62;30&#60;/value&#62;
  &#60;read-only&#62;false&#60;/read-only&#62;
&#60;/preference&#62;
</programlisting>
				<para>
					Again, the <parameter>0</parameter> value means an unlimited upload size, and the value unit is set in MegaBytes.
				</para>
			</step>
			<step>
				<para>
					Use the <literal>getUploadDataAsStream()</literal> method to get the uploaded data:
				</para>
				
<programlisting language="java">UIFormUploadInput input = (UIFormUploadInput)uiForm.getUIInput(&#34;upload&#34;);
InputStream inputStream = input.getUploadDataAsStream();
...
jcrData.setValue(inputStream);
</programlisting>
			</step>
			<step>
				<para>
					The upload service stores a temporary file on the file system during the upload process. When the upload is finished, the service must be cleaned to:
				</para>
				<orderedlist numeration="arabic">
					<listitem>
						<para>
							Delete the temporary file.
						</para>
					</listitem>
					<listitem>
						<para>
							Delete the classes used for the upload.
						</para>
					</listitem>
				</orderedlist>
				<para>
					Use the<literal>removeUpload()</literal> method defined in the upload service to purge the file:
				</para>
				
<programlisting language="java">UploadService uploadService = uiForm.getApplicationComponent(UploadService.class) ;
UIFormUploadInput uiChild = uiForm.getChild(UIFormUploadInput.class) ;
uploadService.removeUpload(uiChild.getUploadId()) ;
</programlisting>
				<note>
					<title>Saving the uploaded file</title>
					<para>
						Ensure the file is saved <emphasis role="bold">before</emphasis> the service is cleaned.
					</para>
				</note>
			</step>
		</procedure>

	</section>

</section>


