Filetools: Unterschied zwischen den Versionen

Aus Physik
Zur Navigation springen Zur Suche springen
Zeile 198: Zeile 198:
   
 
=[http://itp.tugraz.at/Proj/MLTutor/filetools_doc/ Javadoc]=
 
=[http://itp.tugraz.at/Proj/MLTutor/filetools_doc/ Javadoc]=
  +
  +
=Matlab Update=
  +
Hier werden jene Schritte beschrieben, die bei einem Matlab-Update notwendig sind, um den MLTutor und die Datenbank auf den neuesten Stand zu bringen.

Version vom 25. März 2007, 15:22 Uhr

Die grundlegende Idee hinter diesen Tools ist, Klassen zur Verfügung zu stellen, die sowohl eigenständig (konkrete Klassen mit main(...) Methode) als auch von anderen Modulen aus verwendet werden können. Für letztere Variante wird in jedem Paket ein allgemeines Interface definiert, sodass die Klassen möglichst allgemein benutzt weden kann (z.B. in einer Strategy).

Package filesearchtools

Beinhaltet Klassen zum Durchsuchen von Verzeichnisstrukturen.

Interface

public interface IFileSearch {
    abstract public int searchDir(File searchDir); 
}

Einfache Basisklasse

public abstract class SimpleFileSearch implements IFileSearch {
    public SimpleFileSearch(File outputFile){}
    public int searchDir(File searchdir){}
    abstract protected boolean isDirToSearch(String dir);
    abstract protected boolean isSearchedFileName(String filename);
    abstract protected void processFile(File file);
}

Kapselt Funktionalität zum Durchsuchen einer Verzeichnisstruktur.

Konkrete Klassen müssen Funktionen überschreiben, in denen spezifiziert wird, welche Files in welchen Verzeichnissen gesucht werden. In processFile(File) wird definiert wie mit einem "gefundenen" File umgegangen wird.

Konkrete Klasse MatlabfunctionFileSearch

public class MatlabfunctionFileSearch extends SimpleFileSearch{
    public static void main(String[] args) {}
    public MatlabfunctionFileSearch(File outputFile, File syncFile, Vector<String> syncDirs, boolean syncMode){}
    ...
}

Sucht Files, die Matlab-Funktionen beinhalten und speichert den Namen jedes Files (und somit der Funktion) als primitives ASCII File, wobei in jeder Zeile ein Name steht. Zeilentrennung erfolgt mit "\n". Es ist auch möglich eine Synchronisierung mit der Matlab-Hilfe durchzuführen, wobei in diesem Falle ein weiteres File gleicher Struktur erzeugt wird, in welchem alle Funktionen, für die (k)ein Hilfefile direkt gefunden wurde, aufgelistet sind.

Es werden .m Files gesucht, deren Name nicht mit einem Großbuchstaben anfängt. Dabei werden alle Verzeichnisse, die nicht mit "@" anfangen, durchsucht.

Verwendung als Anwendung

$ java filetools/filesearchtools/MatlabfunctionFileSearch -d <directory> 
       [-o <outputfile>] [-ds <sync_directory>] [-os <sync_outputfile>] [-sm <syncmode>]

-d gibt ein Verzeichnis an, in welchem (rekursiv) gesucht werden soll. Es können beliebig viele Verzeichnisse angegeben werden (jedes mit -d vorher!)
-o Name des Ausgabefiles für die Liste der Funktionen. Wird keiner angegeben, so wird das File matlab_funcs verwendet.
-ds Verzeichnis in dem nach den Hilfefiles gesucht wird, jedoch nicht in dessen Unterverzeichnissen. Es können mehrere Verzeichnisse angegeben werden, um die Synchronisierung durchzuführen muss jedoch mindestens eines genannt werden.
-os Name des Ausgabefiles für die Liste der Funktionen ohne Hilfefile. Wird keiner angegeben, so wird das File matlab_funcs_sync verwendet.
-sm Modus für die Synchronisierung. Wenn '0' angegeben wird, dann werden jene Files, für die es ein Hifefile gibt, gespeichert, bei jedem anderen Wert (keine Angabe ist unzulässig!) jene, für die kein Hilfefile existiert, was auch der Fall ist wenn dieser Parameter nicht gesetzt wird,

Konkrete Klasse MatlabHelpfileIndexer

public class MatlabHelpfileIndexer extends SimpleFileSearch{
    public static void main(String[] args) {}
    public MatlabHelpfileIndexer(){}
    public static boolean writeDefaultProperties(String filename){}
    ...
}

Sucht Matlab Hilfefiles (.htm und .html), analysiert diese und speichert die Ergebnisse in einer mySQL Datenbank. Informationen werden gewonnen aus dem Dateinamen, aus den Informationen, die in den meisten Files als Kommentar im head enthalten sind, aus dem title und aus weiteren Tags im File (derzeit nur frameset).

Datenbankschema

+-------------+-------------------------------------------------------------+------+-----+---------+----------------+
| Field       | Type                                                        | Null | Key | Default | Extra          |
+-------------+-------------------------------------------------------------+------+-----+---------+----------------+
| ID          | int(11)                                                     |      | PRI | NULL    | auto_increment |
| filename    | tinytext                                                    |      |     |         |                |
| abspath     | text                                                        |      |     |         |                |
| docname     | text                                                        | YES  | MUL | NULL    |                |
| chunkname   | text                                                        | YES  |     | NULL    |                |
| chapname    | text                                                        | YES  |     | NULL    |                |
| pagetype    | enum('REGULAR','FRAMEPAGE','INDEXPAGE','NAVPAGE','TOCPAGE') |      |     | REGULAR |                |
| title       | text                                                        | YES  | MUL | NULL    |                |
| specialdata | text                                                        | YES  | MUL | NULL    |                |
+-------------+-------------------------------------------------------------+------+-----+---------+----------------+

Erzeugen der Tabelle

CREATE TABLE `helpfiletable` (
  `ID` int(11) NOT NULL auto_increment,
  `filename` tinytext NOT NULL,
  `abspath` text NOT NULL,
  `docname` text,
  `chunkname` text,
  `chapname` text,
  `pagetype` enum('REGULAR','FRAMEPAGE','INDEXPAGE','NAVPAGE','TOCPAGE') NOT NULL default 'REGULAR',
  `title` text,
  `specialdata` text,
  PRIMARY KEY  (`ID`),
  FULLTEXT KEY `title` (`title`),
  FULLTEXT KEY `docname` (`docname`,`chunkname`,`chapname`),
  FULLTEXT KEY `specialdata` (`specialdata`)
) TYPE=MyISAM AUTO_INCREMENT=1284 ;

Konfigurationsfile

Die Daten für die Datenbankverbindung können in einem Konfigurationsfile abgelegt werden. Derzeit ist dessen Name auf dbproperties.xml festgelegt (d.h. es muss im aktuellen Verzeichnis liegen). Es ist ein zur java.util.Properties Klasse kompatibles XML-File, dessen Struktur folgendermaßen aussieht:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment></comment>
<entry key="HOSTNAME">xyz</entry>
<entry key="USERPWD">xyz</entry>
<entry key="DBNAME">xyz</entry>
<entry key="USERNAME">xyz</entry>
</properties>

wobei xyz durch passende Parameter zu ersetzen sind.

Verwendung als Anwendung

$ java filetools/filesearchtools/MatlabHelpfileIndexer <directories> [--propertyfile]

wobei <directories> eine Liste von Verzeichnissen ist, die als Ausgangspunkt für die Suche verwendet werden. Die einzelnen Verzeichnisse werden durch Leerzeichen getrennt und es muss mindestens eines angegeben werden, sofern nicht der optionale Parameter verwendet wird. Wird dieser angegeben, so wird das File dbproperties.xml erzeugt, in welchem die Defaultwerte für die Verbindungseinstellungen zur Datenbank abgelegt werden.


Package filegenerators

Beinhaltet Klassen zum Erzeugen von Files.

Interface

public interface IFileGenerator {
    public boolean generateFile(String filename);
    public void setProperties(Properties properties);
}

Einfache Basisklasse

public abstract class HelpFileIndexDBCompendiumGenerator implements IFileGenerator {
    private Statement dbStatement = null;
    protected FileWriter outputFileWriter = null;
    protected Properties properties = null;
   
    public void setProperties(Properties properties){}
    public static Properties readPropertiesFromFile(String filename){}
    public boolean generateFile(String filename) {}
    protected boolean connectToDB(){}
    protected void sendAndProcessQuery(String query) 
            throws SQLException, IOException{}
    protected void includeFile(String filename) 
            throws IOException {}
    protected abstract void processTask();
    protected abstract void processRow(ResultSet row) 
            throws SQLException, IOException;
    protected void startProcessQuery(ResultSet resultSet) 
            throws SQLException, IOException{
    }
    protected void endProcessQuery(ResultSet resultSet) 
            throws SQLException, IOException{
    }
}

Stellt ein Rohgerüst zum Erzeugen von Files mit Daten aus der Matlab-Helpfile Datenbank zur Verfügung. Die Verbindung zur Datenbank ist hier gekapselt, weiters sind generelle Abläufe und Tools implementiert.

Konkrete Klassen müssen Funktionen überschreiben, in denen spezifiziert wird, welche Daten aus der DB geholt werden und wie diese ins File geschrieben werden.

Konkrete Klasse HelpFileWikiIndexGenerator

public class HelpFileWikiIndexGenerator extends HelpFileIndexDBCompendiumGenerator {
     public HelpFileWikiIndexGenerator(){}
     public void setSingleline(boolean singleline){}
     public static void main(String[] args) {}
    ...
}

Es werden alle Hilfefiles zu Matlab-Funktionen aus der Matlab-Reference in Wiki-Syntax in ein File geschrieben. Die Funktionen sind alphabetisch sortiert und werden nach Anfangsbuchstaben in Kapitel eingeteilt. Dabei sind zwei verschiedene Formate für die Auflistung der Funktionen möglich:

  • Eine Tabelle mit 4 (ist einstellbar, 4 passt aber sehr gut) Spalten, wobei in jeder Zelle der Name der Funktion als Link zur Hilfeseite angeführt wird.
  • Eine Tabelle wobei pro Zeile eine Funktion (gleich wie oben) angeführt wird. Zusätzlich wird zu jeder eine kurze Beschreibung angegeben. (singleline-mode)

Verwendung als Anwendung

$ java filetools/filesearchtools/HelpFileWikiIndexGenerator <filename> [--singleline]

Dabei ist <filename> der Name des zu erzeugenden Files. Wird der optionale Parameter angegeben, so wird die zweite Ausgabe-Variante gewählt.

Datenbank und Konfiguration

Gleich wie bei MatlabHelpfileIndexer, allerdings wird hier für die DB lediglich Lesezugriff benötigt.


Package fileconverttools

Interface

public interface IFileConverter {
    abstract public int convertInDir(File inputRootDir, File outputDir); 
}

Einfache Basisklasse

public abstract class SimpleFileConverter implements IFileConverter {
    public SimpleFileConverter(){}
    public int convertInDir(File inputDir, File outputDir){}
    protected void copyFile(File inputFile, File outputFile);
    abstract protected void convertFile(File inputFile, File outputFile);
    abstract protected boolean isDirToConvert(String dir);
    abstract protected boolean isFileToConvert(String filename);
    abstract protected boolean isFileToCopy(String filename);
}

Kapselt Funktionalität zum Kopieren einer Verzeichnisstruktur, wobei gewisse Files konvertiert werden. Eine einfache Kopierfunktion wird zur Verfügung gestellt. In dieser wird ein File über Streams blockweise (1k) kopiert.

Von ihr müssen konkrete Klassen abgeleitet werden, welche die durchzuführenden Operationen implementieren.

Konkrete Klasse MatlabHelpfileConverter

public class MatlabHelpfileConverter extends SimpleFileConverter{
    public static void main(String[] args) {}
    ...
}

Mit dieser Klasse kann eine Kopie des Inhalts eines Verzeichnisses erstellt werden, wobei .htm und .html Files konvertiert werden. Die Konvertierung besteht darin, dass Links der Form <a href="file:xxxxxxxx durch <a href="xxxxxxxx ausgetauscht werden. Dies erfolgt indem jedes Vorkommen der regex 'href\s*=\s*"file:' ersetzt wird durch 'href="'.

Verwendung als Anwendung

$ java filetools/fileconverttools/MatlabHelpfileConverter -i <input-directory> [-o <output-directory>]

Wird kein output-directory angegeben, so wird innerhalb des input-directories konvertiert (und man erspart sich das Kopieren der restlichen Dateien).


Javadoc

Matlab Update

Hier werden jene Schritte beschrieben, die bei einem Matlab-Update notwendig sind, um den MLTutor und die Datenbank auf den neuesten Stand zu bringen.