<?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 <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 <emphasis>portlet.xml</emphasis> or <emphasis>portlet-preferences.xml</emphasis>:

				</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>

</section>


