Class UIFileUpload

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.UIComp
com.iizix.prop.ui.UIFileUpload
All Implemented Interfaces:
EventListener, IFocusComp, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IUIComp, IUIFocusComp, IVSComponentListener, IVSComponentState, IVSFieldListener, Cloneable
Direct Known Subclasses:
EUIFileUpload
public class UIFileUpload extends UIComp implements IUIFocusComp
File Upload UI component: a drop zone, a picker button, an overall progress bar, a file list with per-file controls and a small log, each region switched by a property (design UPLOAD-UI-DESIGN.md edition 2, section 3).

The component is where a client's request to upload files is allowed or refused. The client component raises the remote event REMOTE_REQUEST carrying what it declares - every file's name, type and size. The request then passes three gates, in this order:

  1. it must be readable (UploadChannelProps.decodeRequest(PropCnr,GProp)), else the client is answered refused protocol;
  2. it must respect this component's own limits: isMultiple(), getMaxFiles(), getMaxFileSize(), getMaxTotalSize() and getAccept(), checked on the declared values;
  3. the App must allow it: the listeners (IUIFileUploadListener.onUploadRequest(UIFileUpload, UploadRequest)) are asked first, then the method tagged with @OnUIUpload; a deny by either wins.
A request that passes is reserved through the file upload API of the client session (IClientUploadAPI.reserve(UploadRequest, IFileUploadListener)), where the upload service applies its own limits, with this component's link as the listener of the reservation; a request that does not is refused there (IClientUploadAPI.refuse(UploadRequest, String)). Either way the client gets ONE answer. A reservation can only answer a client's request: App code cannot make one.

Disposal does not cancel. When the component is disposed of, its link is removed from the reservations it made and nothing else: the transfers continue, heard by the listeners of the client session and of the application session.

Author:
Christopher Mindus

  • Field Details

    • REMOTE_REQUEST

      public static final int REMOTE_REQUEST
      Client to server remote event: the client asks to upload files. Its parameters are those of the upload channel's RESERVE, with the types the component accepts.
      See Also:

    • REASON_TOO_MANY

      public static final String REASON_TOO_MANY
      Refusal reason: more files than the component takes in one pick or drop.
      See Also:

    • REASON_TOO_LARGE

      public static final String REASON_TOO_LARGE
      Refusal reason: a file is larger than the component's maximum file size.
      See Also:

    • REASON_TOTAL_TOO_LARGE

      public static final String REASON_TOTAL_TOO_LARGE
      Refusal reason: the files together are larger than the component's maximum total size.
      See Also:

    • REASON_TYPE

      public static final String REASON_TYPE
      Refusal reason: a file is of a type the component does not accept.
      See Also:

    • CAPTURE_NONE

      public static final int CAPTURE_NONE
      The camera choice of getCapture(): none, the files and the gallery are offered.
      See Also:

    • CAPTURE_REAR

      public static final int CAPTURE_REAR
      The camera choice of getCapture(): the rear camera.
      See Also:

    • CAPTURE_FRONT

      public static final int CAPTURE_FRONT
      The camera choice of getCapture(): the front camera.
      See Also:

  • Constructor Details

    • UIFileUpload

      public UIFileUpload()
      Creates the component without a name. The name must be set in all cases using the setPropertyAtom call.

    • UIFileUpload

      public UIFileUpload(Atom propertyAtom)
      Creates the component with the specified name. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - the name of the component, unique within it's parent.

    • UIFileUpload

      public UIFileUpload(Atom propertyAtom, GProp<?>[] newValue) throws PropException
      Creates the component with the specified name, initialized to contain the GProp items. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - The name of the component, unique within it's parent.
      newValue - The array of all properties the component should have.
      Throws:
      PropException - when at least one of the properties to initialize the component with is invalid.

  • Method Details

    • clone

      public UIFileUpload clone()
      Creates a clone out of this property. The clone has no listeners, no link and no reservations of its own: the listener holder is never shared between the original and the clone, so a listener added to one is not called for the other.

      Cloning is used for "virtualization" of a property tree in the server.

      Note that the cloning process is done WITHOUT thread synchronization for performance reasons, thus no modifications should be done to the tree!

      Overrides:
      clone in class UIComp

    • getDeviceType

      public final int getDeviceType()
      Gets the device type: -1=mobile, 0=both, 1=desktop.
      Specified by:
      getDeviceType in interface IUIComp

    • onPrepare

      protected void onPrepare(ClassReference cr, List<Throwable> errors)
      Called to resolve methods for the component from main "onPrepare" once the ClassReference has been found.
      Overrides:
      onPrepare in class UIComp
      Parameters:
      cr - The class reference with a valid reference.
      errors - The list of errors that is returned to the caller in case resolving fails.

    • getOnUIUploadMethod

      public Method getOnUIUploadMethod()
      Returns the method to use for onUIUpload notifications that is attached to this component. The method name is not important, but must have the annotation and signature:

      @OnUIUpload(name = "some/property")
      public void onUIUpload(UIUploadEvent event)

      Returns:
      The method, or null if none is registered.

    • getUploadAPI

      protected IClientUploadAPI getUploadAPI()
      Gets the file upload API of the client session this component belongs to.
      Returns:
      The API, or null if the component is not in the panel tree of a server client session.

    • getUploadChannel

      protected UploadChannelProps getUploadChannel()
      Gets the upload channel of the client session this component belongs to: where a request that cannot be read is answered, since no UploadRequest exists to refuse.
      Returns:
      The channel, or null if the client created none or the component is not in the panel tree of a client session.

    • onRemoteEvent

      public void onRemoteEvent(RemoteEvent event)
      Called when a remote property event should be processed by this property.
      Specified by:
      onRemoteEvent in interface IGProp<GProp<?>[]>
      Overrides:
      onRemoteEvent in class UIComp
      Parameters:
      event - The remote event.

    • onPropDispose

      protected void onPropDispose()
      Called when a property is disposed of by delete/remove in a container, or by the dispose method.

      The link of this component is removed from the reservations it made, and nothing else: no transfer is cancelled. The files continue to upload, heard by the listeners of the client session and of the application session.

      Overrides:
      onPropDispose in class UIComp

    • mustHaveWidth

      public boolean mustHaveWidth()
      Does this component require a width?
      Overrides:
      mustHaveWidth in class UIComp
      Returns:
      true if the width must be defined and non-zero, false otherwise.

    • mustHaveHeight

      public boolean mustHaveHeight()
      Does this component require a height?
      Overrides:
      mustHaveHeight in class UIComp
      Returns:
      true if the height must be defined and non-zero, false otherwise.

    • mustHaveExplicitWidth

      public boolean mustHaveExplicitWidth()
      Does this component require an explicitly defined width?
      Overrides:
      mustHaveExplicitWidth in class UIComp
      Returns:
      true if the width must be defined and non-zero, false otherwise.

    • mustHaveExplicitHeight

      public boolean mustHaveExplicitHeight()
      Does this component require an explicitly defined height?
      Overrides:
      mustHaveExplicitHeight in class UIComp
      Returns:
      true if the height must be defined and non-zero, false otherwise.

    • hasImplicitAlignFillX

      public boolean hasImplicitAlignFillX()
      Returns if the component has implicit component horizontal fill.
      Overrides:
      hasImplicitAlignFillX in class UIComp
      Returns:
      Always true: true means component will always fill the space in X.

    • hasImplicitAlignFillY

      public boolean hasImplicitAlignFillY()
      Returns if the component has implicit component vertical fill.
      Overrides:
      hasImplicitAlignFillY in class UIComp
      Returns:
      Always: true means component will always fill the space in Y.

    • canAlignX

      public boolean canAlignX()
      Returns if the component can be aligned left, right, center, or horizontal fill.
      Overrides:
      canAlignX in class UIComp
      Returns:
      false, the component takes up the entire width.

    • canAlignY

      public boolean canAlignY()
      Returns if the component can be aligned top, bottom, middle or vertical fill.
      Overrides:
      canAlignY in class UIComp
      Returns:
      false, the component takes up the entire height.

    • getApproximateSize

      public Size getApproximateSize()
      Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method.
      Specified by:
      getApproximateSize in class UIComp
      Returns:
      The size 320x220.

    • addListener

      public boolean addListener(IUIFileUploadListener listener)
      Adds a new listener for the upload requests and the files of this component. Calling this method multiple times with the same listener will have no effect (but to return false).
      Parameters:
      listener - The listener to add.
      Returns:
      true if the listener was added, false otherwise.
      Throws:
      NullPointerException - If the listener is null.

    • removeListener

      public boolean removeListener(IUIFileUploadListener listener)
      Removes a listener of this component.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if listener is successfully removed, false otherwise.

    • getReservationIDs

      public List<String> getReservationIDs()
      Gets the IDs of the live reservations made through this component: accepted, and not yet final in every file.
      Returns:
      The reservation IDs, never null; a snapshot.

    • isMultiple

      public boolean isMultiple()
      Gets if one pick or drop may hold several files.
      Returns:
      true (default) for several files, false for one file: a drop of several is then refused.

    • setMultiple

      public boolean setMultiple(boolean isMultiple)
      Sets if one pick or drop may hold several files.
      Parameters:
      isMultiple - true (default) for several files, false for one file.
      Returns:
      true if changed, false for no change.

    • getMaxFiles

      public int getMaxFiles()
      Gets the maximum number of files of one pick or drop.
      Returns:
      The maximum, zero (default) for the maximum of the server.

    • setMaxFiles

      public boolean setMaxFiles(int maxFiles)
      Sets the maximum number of files of one pick or drop. The server clamps it to its own maximum.
      Parameters:
      maxFiles - The maximum, zero (default) for the maximum of the server.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If maxFiles is less than zero or larger than 10000.

    • getMaxFileSize

      public long getMaxFileSize()
      Gets the maximum size of one file.
      Returns:
      The maximum in bytes, zero (default) for the maximum of the server.

    • setMaxFileSize

      public boolean setMaxFileSize(long maxFileSize)
      Sets the maximum size of one file.
      Parameters:
      maxFileSize - The maximum in bytes, zero (default) for the maximum of the server.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If maxFileSize is less than zero.

    • getMaxTotalSize

      public long getMaxTotalSize()
      Gets the maximum size of the files of one pick or drop together.
      Returns:
      The maximum in bytes, zero (default) for only the quota of the session.

    • setMaxTotalSize

      public boolean setMaxTotalSize(long maxTotalSize)
      Sets the maximum size of the files of one pick or drop together.
      Parameters:
      maxTotalSize - The maximum in bytes, zero (default) for only the quota of the session.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If maxTotalSize is less than zero.

    • getAccept

      public String getAccept()
      Gets the accepted types.
      Returns:
      The types in the syntax of the HTML accept attribute, separated by comma: a file name extension (.pdf), a family (image/*) or a media type (application/zip); empty (default) for any file. Never null.

    • setAccept

      public boolean setAccept(String accept)
      Sets the accepted types. They are checked on the client, on the declared type and name of a request, and by the upload service on the verified type of the file.
      Parameters:
      accept - The types in the syntax of the HTML accept attribute, separated by comma: a file name extension (.pdf), a family (image/*) or a media type (application/zip); null or empty for any file.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If an entry is neither of the three forms.

    • isAutoStart

      public boolean isAutoStart()
      Gets if the upload starts at once when files are picked or dropped.
      Returns:
      true (default) to start at once, false if the files wait in the list for the Upload button.

    • setAutoStart

      public boolean setAutoStart(boolean isAutoStart)
      Sets if the upload starts at once when files are picked or dropped.
      Parameters:
      isAutoStart - true (default) to start at once, false if the files wait in the list for the Upload button.
      Returns:
      true if changed, false for no change.

    • getCapture

      public int getCapture()
      Gets the camera the picker opens on a device that has one.
      Returns:
      CAPTURE_NONE (default), CAPTURE_REAR or CAPTURE_FRONT.

    • setCapture

      public boolean setCapture(int capture)
      Sets the camera the picker opens on a device that has one. It applies only when the accepted types are images or videos.
      Parameters:
      capture - CAPTURE_NONE (default), CAPTURE_REAR or CAPTURE_FRONT.
      Returns:
      true if changed, false for no change.
      Throws:
      IllegalArgumentException - If capture is not one of the three values.

    • getGroup

      public String getGroup()
      Gets the upload group: carried to IUploadFile.getGroup() of every file of this component, for the App.
      Returns:
      The group, empty (default) for none. Never null.

    • setGroup

      public boolean setGroup(String group)
      Sets the upload group.
      Parameters:
      group - The group, null or empty for none.
      Returns:
      true if changed, false for no change.

    • isNotices

      public boolean isNotices()
      Gets if a failure of this component's files is shown to the user by IIZI.
      Returns:
      true (default) for the automatic failure notice, false if the App reports failures itself.

    • setNotices

      public boolean setNotices(boolean isNotices)
      Sets if a failure of this component's files is shown to the user by IIZI.
      Parameters:
      isNotices - true (default) for the automatic failure notice, false if the App reports failures itself.
      Returns:
      true if changed, false for no change.

    • getHint

      public PlainKString getHint()
      Gets the drop hint.
      Returns:
      The text replacing the default hint of the drop zone, null for the default.

    • setHint

      public boolean setHint(String hint)
      Sets the drop hint.
      Parameters:
      hint - The text replacing the default hint of the drop zone, null for the default.
      Returns:
      true if changed, false for no change.

    • getPickText

      public PlainKString getPickText()
      Gets the text of the picker button.
      Returns:
      The text replacing the default text of the picker button, null for the default.

    • setPickText

      public boolean setPickText(String text)
      Sets the text of the picker button.
      Parameters:
      text - The text replacing the default text of the picker button, null for the default.
      Returns:
      true if changed, false for no change.

    • getUploadText

      public PlainKString getUploadText()
      Gets the text of the Upload button, shown when isAutoStart() is off.
      Returns:
      The text replacing the default text of the Upload button, null for the default.

    • setUploadText

      public boolean setUploadText(String text)
      Sets the text of the Upload button, shown when isAutoStart() is off.
      Parameters:
      text - The text replacing the default text of the Upload button, null for the default.
      Returns:
      true if changed, false for no change.

    • isShowDrop

      public boolean isShowDrop()
      Gets if the drop zone is shown. Ignored on touch devices.
      Returns:
      true (default) if shown.

    • setShowDrop

      public boolean setShowDrop(boolean isShown)
      Sets if the drop zone is shown. Ignored on touch devices.
      Parameters:
      isShown - true (default) to show it.
      Returns:
      true if changed, false for no change.

    • isShowPicker

      public boolean isShowPicker()
      Gets if the picker button is shown.
      Returns:
      true (default) if shown.

    • setShowPicker

      public boolean setShowPicker(boolean isShown)
      Sets if the picker button is shown.
      Parameters:
      isShown - true (default) to show it.
      Returns:
      true if changed, false for no change.

    • isShowProgress

      public boolean isShowProgress()
      Gets if the overall progress bar is shown.
      Returns:
      true (default) if shown.

    • setShowProgress

      public boolean setShowProgress(boolean isShown)
      Sets if the overall progress bar is shown.
      Parameters:
      isShown - true (default) to show it.
      Returns:
      true if changed, false for no change.

    • isShowList

      public boolean isShowList()
      Gets if the file list is shown: per file its name, size, bar, state and controls.
      Returns:
      true (default) if shown.

    • setShowList

      public boolean setShowList(boolean isShown)
      Sets if the file list is shown.
      Parameters:
      isShown - true (default) to show it.
      Returns:
      true if changed, false for no change.

    • isShowLog

      public boolean isShowLog()
      Gets if the log window is shown: the last 50 events of this component's files.
      Returns:
      true if shown, false (default) if not.

    • setShowLog

      public boolean setShowLog(boolean isShown)
      Sets if the log window is shown.
      Parameters:
      isShown - true to show it, false (default) to hide it.
      Returns:
      true if changed, false for no change.

    • isAllowPause

      public boolean isAllowPause()
      Gets if the user can pause and resume a file.
      Returns:
      true (default) if the per-file buttons are offered.

    • setAllowPause

      public boolean setAllowPause(boolean isAllowed)
      Sets if the user can pause and resume a file.
      Parameters:
      isAllowed - true (default) to offer the per-file buttons.
      Returns:
      true if changed, false for no change.

    • isAllowCancel

      public boolean isAllowCancel()
      Gets if the user can cancel a file.
      Returns:
      true (default) if the per-file button is offered.

    • setAllowCancel

      public boolean setAllowCancel(boolean isAllowed)
      Sets if the user can cancel a file.
      Parameters:
      isAllowed - true (default) to offer the per-file button.
      Returns:
      true if changed, false for no change.

    • isAllowRetry

      public boolean isAllowRetry()
      Gets if the user can send a failed file again, as a new reservation.
      Returns:
      true (default) if the per-file button is offered.

    • setAllowRetry

      public boolean setAllowRetry(boolean isAllowed)
      Sets if the user can send a failed file again, as a new reservation.
      Parameters:
      isAllowed - true (default) to offer the per-file button.
      Returns:
      true if changed, false for no change.

    • checkAccept

      public static String checkAccept(String accept)
      Checks the syntax of accepted types.
      Parameters:
      accept - The types, separated by comma.
      Returns:
      null if every entry is a file name extension (.ext), a family (type/*) or a media type (type/subtype), otherwise the error text.

    • verify

      public boolean verify(PropVerification verification)
      Verifies this property container.
      Specified by:
      verify in interface IGProp<GProp<?>[]>
      Overrides:
      verify in class UIComp
      Parameters:
      verification - The property verification class.
      Returns:
      true if verification should proceed, false if disposed of and verification should not take place.