4 <basefont size="4" color="#2F4958" face="arial">
6 <H1>Custom import filters</H1>
8 <p>JabRef allows you to define and use your own importers, in very much the same way as the
9 standard import filters are defined. An import filter is defined by one or more
10 Java <i>classes</i>, which parse the contents of a file from an input stream
11 and create BibTex-Entries. So with some basic Java programming you can add an importer
12 for your favorite source of references or register a new, improved version of an existing
13 importer. Also, this allows you to add compiled custom importers that you might
14 have obtained e.g. from SourceForge without rebuilding JabRef (see "Sharing your work").</p>
16 <p>Custom importers take precedence over standard importers. This way, you can override
17 existing importers for the Autodetect and Command Line features of JabRef. Custom importers
18 are ordered by name.</p>
20 <H2>Adding a custom import filter</H2>
22 <p>Make sure, you have a compiled custom import filter (one or more <code>.class</code> files
23 as described below) and the class files are in a directory structure according to
24 their package structure. To add a new custom import filter, open the dialog box
25 <b>Options -> Manage custom imports</b>, and click <b>Add from folder</b>.
26 A file chooser will appear, allowing you to select the classpath of your importer,
27 i.e. the directory where the top folder of the package structure of your importer
28 resides. In a second file chooser you select your importer
29 class file, which must be derived from <code>ImportFormat</code>. By clicking
30 <b>Select new ImportFormat Subclass</b>, your new importer will appear in the list
31 of custom import filters. All custom importers will appear in the <b>File -> Import ->
32 Custom Importers</b> and <b>File -> Import and Append -> Custom Importers</b> submenus
33 of the JabRef window.</p>
35 <p>Please note that if you move the class to another directory you will have to
36 remove and re-add the importer. If you add a custom importer under a name that
37 already exists, the existing importer will be replaced. Although in some cases
38 it is possible to update an existing custom importer without restarting JabRef
39 (when the importer is not on the classpath), we recommend restarting JabRef
40 after updating an custom-importer. You can also register importers
41 contained in a ZIP- or JAR-file, simply select the Zip- or Jar-archive, then the
42 entry (class-file) that represents the new importer.</p>
44 <H2>Creating an import filter</H2>
46 For examples and some helpful files on how to build your own importer, please check
49 <H3>A simple example</H3>
51 <p>Let us assume that we want to import files of the following form:
53 1936;John Maynard Keynes;The General Theory of Employment, Interest and Money
54 2003;Boldrin & Levine;Case Against Intellectual Monopoly
55 2004;ROBERT HUNT AND JAMES BESSEN;The Software Patent Experiment
58 <p>In your favorite IDE or text editor create a class derived from <code>ImportFormat</code>
59 that implements methods <code>getFormatName()</code>, <code>isRecognizedFormat</code>
60 and <code>importEntries()</code>. Here is an example:
64 import net.sf.jabref.*;
65 import net.sf.jabref.imports.ImportFormat;
66 import net.sf.jabref.imports.ImportFormatReader;
68 public class SimpleCsvImporter extends ImportFormat {
70 public String getFormatName() {
71 return "Simple CSV Importer";
74 public boolean isRecognizedFormat(InputStream stream) throws IOException {
75 return true; // this is discouraged except for demonstration purposes
78 public List importEntries(InputStream stream) throws IOException {
79 ArrayList bibitems = new ArrayList();
80 BufferedReader in = new BufferedReader(ImportFormatReader.getReaderDefaultEncoding(stream));
82 String line = in.readLine();
83 while (line != null) {
84 if (!"".equals(line.trim())) {
85 String[] fields = line.split(";");
86 BibtexEntry be = new BibtexEntry(Util.createNeutralId());
87 be.setType(BibtexEntryType.getType("techreport"));
88 be.setField("year", fields[0]);
89 be.setField("author", fields[1]);
90 be.setField("title", fields[2]);
100 <p>Note that the example is in the default package. Suppose you have saved it
101 under <code>/mypath/SimpleCsvImporter.java</code>. Also suppose the JabRef-2.0.jar is in the
102 same folder as <code>SimpleCsvImporter.java</code> and Java is on your command path.
103 Compile it using a JSDK 1.4 e.g. with
105 javac -classpath JabRef-2.0.jar SimpleCsvImporter.java
107 Now there should be a file <code>/mypath/SimpleCsvImporter.class</code>.</p>
109 <p>In JabRef, open <b>Options -> Manage custom imports</b>, and click <b>Add from folder</b>.
110 Navigate to <code>/mypath</code> and click the <b>Select ...</b> button. Select the
111 <code>SimpleCsvImporter.class</code> and click the <b>Select ...</b> button.
112 Your importer should now appear in the list of custom importers under the name
113 "Simple CSV Importer" and, after you click <b>Close</b> also in the <b>File -> Import ->
114 Custom Importers</b> and <b>File -> Import and Append -> Custom Importers</b> submenus
115 of the JabRef window.</p>
117 <H2>Sharing your work</H2>
119 <p>With custom importer files, it's fairly simple to share custom import formats between users.
120 If you write an import filter for a format not supported by JabRef, or an improvement over an
121 existing one, we encourage you to post your work on our SourceForge.net page. We'd be happy to
122 distribute a collection of submitted import files, or to add to the selection of standard