Main Page

From fupco (inactive) Wiki
Jump to: navigation, search

Contents

Zusammenfassung

Die Datei-Upload-Komponente (File Upload Component) bietet anderen Web-Applikationen die Möglichkeit, hochgeladene Dateien nach verschiedenen (erweiterbaren) Kriterien zu prüfen. Im Verlauf dieser Prüfungen sind auch Modifikationen (zum Beispiel das Entfernen von Viren oder das Hinzufügen von Wasserzeichen) möglich.

Konfiguration

In die nutzende Anwendung ist die Bibliothek fupco-lib einzubinden. In Maven-Projekten werden die benötigten Abhängigkeiten automatisch aufgelöst. Die weitere Konfiguration hängt von den verwendeten Checks ab. Soll zum Beispiel der enthaltene Virus-Scan erfolgen, so muss ein FProt-Virenscanner installiert und konfiguriert sein.

Benutzung

Validator

Zentraler Punkt der Fupco-Komponente ist die Validator-Klasse. Diese verfügt über die überladene validate()-Methode welche wahlweise einen java.io.InputStream-, oder ein java.io.File-Objekt und eine Instanz der Configuration-Klasse als Methodenparameter akzeptiert. Die validate()-Methoden führen die im Configuration-Objekt konfigurierten Checks mit den dort konfigurierten Parametern für diese aus.

Ist der Validator nicht in Lage, die konfigurierten Checks zu instanziieren, oder wie gewünscht zu konfigurieren, wirft er eine ValidatorInitException.

Der Rückgaberwert der validate()-Methoden ist immer vom Typ UploadedFile. Aus diesem zurückgegebenen Objekt lassen sich Informationen über den Erfolg und den Mißerfolg der Überprüfung der hochgeladenen Datei ziehen.

Configuration

Das von den validate()-Methoden genutzte Objekt vom Typen Configuration enthält immer die zum validieren der hochgeladenen Datei vorgesehenen Checks. Die Check-Objekte in der Configuration-Instanz sind immer fertig konfiguriert, das bedeutet, dass sie über ihre Parameter verfügen.

Da jeder Aufruf einer validate()-Methode im Validator ein gültiges Objekt vom Typ Configuration erfordert, ist so das Ändern von Konfigurationsparametern zur Laufzeit des Servlet-Containers möglich. Ein Objekt vom Typ Configuration kann einfach im Code erstellt werden. Hierzu müssen dann die auszuführenden Checks instantiiert und konfiguriert werden und dem Configuration-Objekt über die addVerifyingCheck()-, beziehungsweise addModifyingCheck()-Methode hinzugefügt werden.

ConfigReader

Alternativ zur programmatischen Konfiguration können die Objekte vom Typ Configuration auch über den ConfigReader erstellt werden. Hierzu dient die statische Methode readConfig() in eben dieser Klasse, die als Parameter den Pfad zu einer XML-Konfigurationsdatei akzeptiert und ein fertig konfiguriertes Objekt vom Typen Configuration zurück gibt. Ein typisches Beispiel für eine Konfigurationsdatei zeigt der nächste Abschnitt.

Fupco-Config-xml-Beispieldatei

<configuration>
  <quarantineDir>/tmp</quarantineDir>
  <checks>
     <check classname="de.tarent.portlets.fupco.checks.MimeTypeCheck">
        <properties>
           <property key="allowedMimeTypes" value="application/msexcel,image/jpeg,image/gif,image/png,image/tiff"/>
           <property key="mimeTypeStringSeperator" value=","/>
        </properties>
     </check>
     <check classname="de.tarent.portlets.fupco.checks.FileSizeCheck">
        <properties>
           <property key="maxFileSize" value="2MB" /> 
        </properties>
     </check>
     <check classname="de.tarent.portlets.fupco.checks.VirusScanningCheck">
        <properties>
           <property key="scannerHost" value="localHost" />
           <property key="scannerPort" value="10200" />
           <property key="acceptableReturnValues" value="0,128" />
        </properties>
     </check>
  </checks>
</configuration>


Checks

Check-Objekte werden in Configuration-Objekten registriert und vom Validator zum validieren der hochgeladenen Datei ausgeführt. Checks definieren Operationen auf die hochgeladene Datei, in denen überprüft wird, ob die hochgeladene Datei spezifizierten Kriterien entspricht und liefern das Ergebnis der Überprüfung zurück.

Ein Check enthält ein Set von benötigten Properties, die mit der Methode getRequiredProperties() abgefragt werden können.Diese Properties müssen vor der Ausführung des Checks mit der withProperty()-Methode gesetzt werden. Die Methode doCheck() führt den Check aus und getCheckResult() gibt ein Objekt vom Typ CheckResult zurück: das Ergebnis des Checks. In der Regel wird hier ein tatsächlich ermittelter Wert (detected value) gesetzt.

Es wird unterschieden zwischen Verifying Checks und Modifying Checks.

VerifiyingCheck

Checks vom Typ VerifyingCheck verändern die hochgelade Datei nicht. Sie führen die in ihnen definierten Überprüfungen aus, belassen die Datei dabei aber wie sie ist und geben lediglich ein CheckResult zurück.

ModifyingCheck

Checks vom Typ ModifyingChecks können die hochgeladene Datei veränden. Sie können zum Beispiel überprüfen, ob die Datei mit einem Virus infiziert ist und diesen entfernen. Oder sie könnten einem Bild ein Wasserzeichen hinzufügen. Ob ein ModifyingCheck eine Datei tatsächlich geändert hat, lässt sich über die Methode isModified() des CheckResult-Objekts abfragen.

Mitgelieferte Checks

Die Fupco liefert von Hause aus einige Checks mit. Diese werden im Folgenden beschrieben.

FileSizeCheck

Der FileSizeCheck überprüft, ob eine Datei eine konfigurierte Dateigröße überschreitet.

Required Properties
  • MAXFILESIZE - die maximal zulässige Dateigröße. Entweder in byte oder mit Hilfe von kB/MB/GB/TB (zB "2MB")
Optional Properties
  • EMPTYFILE_ALLOWED - Ob leere ( 0-Byte große) Dateien akzeptiert werden oder nicht. Default-Wert: "false"
Detected Value

Die ermittelte Dateigröße

Nicht im Interface enthaltene Methoden

keine

MimeTypeCheck

Der MimeTypeCheck überprüft, ob die übergebene Datei einem der konfigurierten erlaubten Mime Types entspricht

Required Properties
  • MIME_TYPE_STRING_SEPERATOR - das oder die Zeichen, mit dem einzelne erlaubte Mime Types voneinander getrennt sind. Muss nicht gesetzt werden (default: ",")
  • MIME_TYPES_ALLOWED - die zulässigen Mime-Types
Detected Value

String-Representation des erkannten Mime-Types

Nicht im Interface enthaltene Methoden
  • getDetectedMimeType() - gibt eine MimeType-Instanz zurück
MimeType

MimeType gibt über getMimeType() einen String zurück, welcher den MimeType repräsentiert und hält unter getExtensions() eine Liste aller bekannten gültigen Dateiendungen für diesen MimeType vor.

VirusScanningCheck

VirusScanningCheck überprüft Dateien mit Hilfe von FProt auf Viren

Required Properties
  • SCANNER_HOST - die Hostadresse des Virenscanners
  • SCANNER_PORT - der Port, auf dem der Virenscanner zu finden ist
  • ACCEPTABLE_RETURN_VALUES - Rückgabewerte, welche zu akzeptieren sind
Detected Value

"infected" oder "clean"

Nicht im Interface enthaltene Methoden

keine

Eigene Checks

Eigene Checks müssen die Interfaces ModifyingCheck oder VerifyingCheck implementieren. Um wiederkehrenden Boilerplate Code zu vermeiden, bietet die Fupco außerdem die abstrakte Klasse AbstractCheck, in der bereits etliche der Vorarbeiten geleistet wurden.

CheckResult

Objekte vom Typ CheckResult-Instanzen werden von Checks über die statischen (überladenen) Factory-Methoden FAIL oder SUCCESS erstellt und vorgehalten. Sie halten Informationen über das Ergebnis des Checks mit den folgenden Methoden vor:

  • isCheckSuccessful() - boolean-value, die das Checkergebnis repräsentiert
  • getMessage() - eine Nachricht des Checks, die beim Erstellen des
  • CheckResult-Objekts übergeben wurde.
  • getDetectedValue() - ein Wert, welcher vom Check gesetzt werden kann
  • getThrowable() - im Falle des Auftretens einer Exception während des Ausführens des Checks kann der Check diese dem Checkresult übergeben damit sie vom Konsumenten ausgewertet werden kann.

UploadedFile

Objekte vom Typ UploadedFile werden vom Validator beim Aufruf von validate() zurück gegeben. Die Methode isValidationSuccess() informiert darüber, ob alle für den Validator konfigurierten Checks erfolgreich waren. Die ausgeführten Checks können über die Methode getExecutedChecks() abgefragt werden. Soll das Ergebnis eines bestimmten Check ausgewertet werden, so steht hierfür die Methode getCheckForClass() zur Verfügung. Die Methode isModified() liefert informiert darüber, ob die hochgeladene Datei wärend der Ausführung der Checks modifiziert wurde.

Die Methode getUploadedFile() liefert ein Objekt vom Typ java.io.File zurück, das eine Referenz auf die hochgeladene Datei bietet.

Exceptions

ValidatorInitException

Eine ValidatorInitException wird geworfen, wenn bei der Initialisierung mit den übergebenen Konfigurationsparametern ein Zustand erreicht wurde, welcher nicht von der Komponente behandelt werden kann. Sie erbt von Exception und bietet darüber hinaus keine Funktionalität.

ValidatorValidationException

Alte Versionen der Fupco haben beim scheitern eines Checks in der validate()-Methode eine ValidatorValidationException geworfen. Diese Methoden sind aber mittlerweile veraltet und sollten nicht mehr genutzt werde. Sie sind in der API als deprecated markiert und werden in einer kommenden Release der Fupco entfernt.

fupco-Portlet und fupco-gwtclient

Die Projekte fupco-Portlet und fupco-gwtclient stellen beispielhafte konsumenten-Komponente für die fupco-lib dar und sind dazu gedacht, sich einen Überblick über die Nutzung der Bibliothek zu verschaffen.

SCM und Repos