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