<?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>
			<para>
			In this section, you will learn how to configure the <emphasis role="bold"> Upload service </emphasis> that is defined by the <emphasis>org.exoplatform.upload.UploadService</emphasis> class.
		</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 uploading files with the default size limit (10MB). The default 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 <emphasis>org.exoplatform.webui.form.input.UIUploadInput</emphasis> object type by using one of three following constructors:

				</para>

                <itemizedlist>
                    <listitem>
                        <para>This is the default constructor that allows uploading the file with the size of 10 MB.</para>
                        <programlisting language="java">public UIUploadInput(String name, String bindingExpression, int limitFile) </programlisting>
                    </listitem>
                    <listitem>
                        <para>
                            This constructor allows you to customize the size limit of uploaded files by using the <emphasis>limitSize</emphasis> parameter. The default value unit is Megabytes.
                        </para>
                        <programlisting language="java">public UIUploadInput(String name, String bindingExpression,int limitFile, int limitSize)</programlisting>
                    </listitem>
                    <listitem>
                        <para>This constructor allows you to customize the size limit and the value unit by using the <emphasis>limitSize</emphasis> and <emphasis>unit</emphasis> parameters respectively.</para>
                        <para>In GateIn, you can set the value unit to Megabytes (MB), Kilobytes (KB) or Gigabytes (GB).</para>
                        <programlisting language="java">public UIUploadInput(String name, String bindingExpression, int limitFile, int limitSize, UploadUnit unit)</programlisting>
                    </listitem>
                </itemizedlist>
				<para>
					The following is an example using the third form:
				</para>
                <programlisting language="java"><![CDATA[PortletRequestContext pcontext = (PortletRequestContext)WebuiRequestContext.getCurrentInstance();
PortletPreferences portletPref = pcontext.getRequest().getPreferences();
int limitFile = Integer.parseInt(portletPref.getValue("uploadFileLimit", "1").trim());
int limitSize = Integer.parseInt(portletPref.getValue("uploadFileSizeLimit", "").trim());
UploadUnit limitUnit = UploadUnit.valueOf(portletPref.getValue("uploadFileLimitUnit", "MB").trim());
UIUploadInput uiInput = new UIUploadInput("upload", "upload", limitFile, limitSize, limitUnit);]]></programlisting>
			</step>
			<step>
				<para>
					To obtain the limit from the <emphasis>XML</emphasis> configuration, add the following code to the either <filename>portlet.xml</filename> or <filename>portlet-preferences.xml</filename>:
				</para>
<programlisting language="xml"><![CDATA[<! The number of files are uploaded -->
    <preference>
        <name>uploadFileLimit</name>
        <value>3</value>
        <read-only>false</read-only>
    </preference>
<! The size limit -->
    <preference>
        <name>uploadFileSizeLimit</name>
        <value>300</value>
        <read-only>false</read-only>
    </preference>
<! The unit limit -->
    <preference>
        <name>uploadFileLimitUnit</name>
        <value>KB</value>
        <read-only>false</read-only>
    </preference> ]]></programlisting>
                <para>
					Note that the <parameter>0</parameter> value means unlimited upload size, and the value unit is set to MegaBytes.
				</para>
			</step>
			<step>
				<para>

					Use the <emphasis>getUploadDataAsStream()</emphasis> method to get the uploaded data:
                </para>
<programlisting language="java">UIUploadInput input = (UIUploadInput)uiForm.getUIInput(&#34;upload&#34;);
InputStream[] inputStreams = input.getUploadDataAsStreams();
...</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>
				<itemizedlist>
					<listitem>
						<para>
							Delete the temporary file.
						</para>
					</listitem>
					<listitem>
						<para>
							Delete the classes used for the upload.
						</para>
					</listitem>
				</itemizedlist>
				<para>
					Use the <literal>removeUploadResource(String uploadId)</literal> method defined in the upload service to purge the file:
                </para>
<programlisting language="java">UploadService uploadService = uiForm.getApplicationComponent(UploadService.class) ;
UIUploadInput uiChild = uiForm.getChild(UIFormUploadInput.class) ;
    for(String uploadId : uiChild.getUploadIds())
    {
    uploadService.removeUpload(uploadId) ;
    }</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>


