File: tutorial.html

package info (click to toggle)
libmarc4j-java 2.9.5-1
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 8,908 kB
sloc: xml: 109,577; java: 22,102; makefile: 7
file content (624 lines) | stat: -rw-r--r-- 48,636 bytes
parent folder | download | duplicates (2)
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>MARC4J tutorial</title><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="N10001"></a>MARC4J tutorial</h1></div><div><p class="copyright">Copyright &copy; 2002-2006 Bas Peters</p></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#N1000E">Introduction</a></span></dt><dt><span class="sect1"><a href="#N1001F">What you should already know</a></span></dt><dt><span class="sect1"><a href="#N10034">Getting the Software</a></span></dt><dt><span class="sect1"><a href="#N1004B">Reading MARC data</a></span></dt><dt><span class="sect1"><a href="#N100B5">The record object model</a></span></dt><dt><span class="sect1"><a href="#N1013B">Reading MARC XML data</a></span></dt><dt><span class="sect1"><a href="#N1015B">Reading MODS data</a></span></dt><dt><span class="sect1"><a href="#N10183">Writing MARC data</a></span></dt><dt><span class="sect1"><a href="#N101BE">Perform character conversions</a></span></dt><dt><span class="sect1"><a href="#N1024E">Advanced MARC XML features</a></span></dt><dt><span class="sect1"><a href="#N10288">Summary</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1000E"></a>Introduction</h2></div></div><div></div></div><p>This tutorial is for library programmers who want to learn to use MARC4J to process MARC and XML data. MARC4J (<a href="http://marc4j.tigris.org" target="_top">http://marc4j.tigris.org</a>) is an open source software library for working with MARC records in Java, a popular platform independent programming language. The MARC (Machine Readable Cataloging) format was originally designed to enable the exchange of bibliographic data between computer systems by providing a structure and format for the storage of bibliographic records on half-inch magnetic tape. Though today most records are transferred by other media, the exchange format has not changed since its first release in 1967 and is still widely used worldwide. At the same time, there is a growing interest in the use of XML in libraries, mainly because the Web is moving towards a platform- and application-independent interface for information services, with XML as its universal data format.</p><p>MARC4J is designed to bridge the gap between MARC and XML. The software library has build-in support for reading and writing MARC and MARC XML data. MARC XML is a simple XML schema for MARC data published by the Library of Congress. MARC4J also provides a "pipeline" to enable MARC records to go through further transformations using XSLT, for example to convert MARC records to MODS (Metadata Object Description Schema). This feature is particular useful there is currently no agreed-upon standard for XML in library applications.</p><p>Although MARC4J can be used as a command-line tool for conversions between MARC and XML, its main goal is to provide an Application Programming Interface (API) to develop any kind of Java program or servlet that involves reading or writing MARC data. The core piece is a MARC reader that hides the complexity of the MARC record by providing a simple interface to extract information from MARC records. Support for XML is implemented using the standard Java XML interfaces as specified in Sun's Java API for XML Processing (<a href="http://www.ifla.org/VI/3/p1996-1/sec-uni.htm" target="_top">JAXP</a>). By limiting itself to the JAXP API, is XML processor-independent and easy to integrate in applications that build on industry standards such as SAX (Simple API for XML) or DOM (Document Object Model).</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1001F"></a>What you should already know</h2></div></div><div></div></div><p>This tutorial assumes that you are interested in developing Java applications that involve MARC and XML. You have a basic understanding of a MARC format like <a href="http://www.loc.gov/marc/" target="_top">MARC 21</a> or <a href="http://www.ifla.org/VI/3/p1996-1/sec-uni.htm" target="_top">UNIMARC</a> and you are familiar with the basics of <a href="http://www.w3.org/XML/" target="_top">XML</a> and related standards like XML Namespaces and XSLT. Working with MARC4J does not require exceptional skills in Java programming. The API is designed to be easy to learn and easy to use. It works very straight-forwardly, and has a very shallow learning curve, so you should be able to get up and running with MARC4J very quickly. If you have no experience with the Java programming language at all, you should start with getting familiar with the basic concepts of the language. Sun's <a href="http://java.sun.com/" target="_top">Java Technology</a> site provides some good introductory tutorials on Java.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10034"></a>Getting the Software</h2></div></div><div></div></div><p>You can download a MARC4J distribution at <a href="http://marc4j.tigris.org" target="_top">http://marc4j.tigris.org</a>. On the project home page you can find a direct link to the distribution at the Download section. You can also find links to MARC4J distributions on the Documents &amp; Files page. A link to this page can be found in the Project tools menu. The latest version at the time of this writing is MARC4J 2.2. The download includes Javadoc documentation, source code and two JAR files: <code class="filename">marc4j.jar</code> and <code class="filename">normalizer.jar</code>. Add both files to your CLASSPATH environment variable.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Starting from release 2.0 MARC4J was completely rebuild. The 2.0 and later releases are not compatible with older versions of MARC4J. The event based parser is replaced by an easier to use interface that uses a simple iterator over a collection of MARC records.</p></div><p>MARC4J requires Sun JDK 1.4 or later because it uses the <code class="classname">java.util.regex</code> package (since version 2.1). The JDK already contains the JAXP and SAX2 compliant XML parser and XSLT processor required by MARC4J, but you can use a different implementation.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1004B"></a>Reading MARC data</h2></div></div><div></div></div><p>For reading MARC data, MARC4J provides implementations of an interface called <code class="classname">org.marc4j.MarcReader</code>. This interface has two methods that provide an iterator to read MARC data from an input source:</p><div class="variablelist"><dl><dt><span class="term"><code class="methodname">hasNext()</code></span></dt><dd><p>Returns true if the iteration has more records, false otherwise.</p></dd><dt><span class="term"><code class="methodname">next()</code></span></dt><dd><p>Returns the next record in the iteration as a <code class="classname">org.marc4j.marc.Record</code> object.</p></dd></dl></div><p>If you are familiar with the Java Collections Framework you might have used iterators. For example when you have <code class="classname">java.util.List</code> in Java you can access the items on the list through a <code class="classname">java.util.Iterator</code> that can be obtained from the <code class="classname">List</code> object:</p><pre class="programlisting">
    Iterator i = list.iterator();
    while (i.hasNext()) {
        Object item = i.next();
        // do something with the item object
    }	
      </pre><p>MARC4J provides two classes that implement <code class="classname">MarcReader</code>:</p><div class="variablelist"><dl><dt><span class="term"><code class="classname">org.marc4j.MarcStreamReader</code></span></dt><dd><p>An iterator over a collection of MARC records in ISO 2709 format.</p></dd><dt><span class="term"><code class="classname">org.marc4j.MarcXmlReader</code></span></dt><dd><p>An iterator over a collection of MARC records in MARC XML format.</p></dd></dl></div><p>Let's start with reading MARC records in ISO 2709 format. To do this we need to import some classes:</p><pre class="programlisting">
    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.marc.Record;
    </pre><p>The first two classes are required to read MARC data and the third class imports the class that represents a MARC record. We also need an input stream to read records from, for example:</p><pre class="programlisting">
    InputStream in = new FileInputStream("summerland.mrc");
    </pre><p>We can then initialize the <code class="classname">org.marc4j.MarcReader</code> implementation with the given input stream:</p><pre class="programlisting">
    MarcReader reader = new MarcStreamReader(in);
    </pre><p>And start reading records:</p><pre class="programlisting">
    while (reader.hasNext()) {
        Record record = reader.next();
    }
    </pre><p>If we simply want to examine the records we can write each record to standard output using the <code class="methodname">toString()</code> method:</p><pre class="programlisting">
    System.out.println(record.toString());
    </pre><p>Here is the complete program:</p><div class="example"><a name="N100A8"></a><p class="title"><b>Example&nbsp;1.&nbsp;A first example</b></p><pre class="programlisting">
    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.marc.Record;
    import java.io.InputStream;
    import java.io.FileInputStream;

    public class ReadMarcExample {

        public static void main(String args[]) throws Exception {

	    InputStream in = new FileInputStream("summerland.mrc");
            MarcReader reader = new MarcStreamReader(in);
            while (reader.hasNext()) {
                 Record record = reader.next();
                 System.out.println(record.toString());
            }    

        }

    }
      </pre></div><p>When you compile and run this program it will write each record in tagged display format to standard output:</p><div class="example"><a name="N100B0"></a><p class="title"><b>Example&nbsp;2.&nbsp;Output in tagged display format</b></p><pre class="programlisting">
    LEADER 00714cam a2200205 a 4500
    001 12883376
    005 20030616111422.0
    008 020805s2002    nyu    j      000 1 eng
    020   $a0786808772
    020   $a0786816155 (pbk.)
    040   $aDLC$cDLC$dDLC
    100 1 $aChabon, Michael.
    245 10$aSummerland /$cMichael Chabon.
    250   $a1st ed.
    260   $aNew York :$bMiramax Books/Hyperion Books for Children,$cc2002.
    300   $a500 p. ;$c22 cm.
    520   $aEthan Feld, the worst baseball player in the history of the game, finds
    himself recruited by a 100-year-old scout to help a band of fairies triumph over
    an ancient enemy.
    650  1$aFantasy.
    650  1$aBaseball$vFiction.
    650  1$aMagic$vFiction.
      </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N100B5"></a>The record object model</h2></div></div><div></div></div><p>Now let's examine the <code class="classname">org.marc4j.marc.Record</code> class more closely. Basically a <code class="classname">Record</code> object provides acces to the leader and variable fields. For example the following method returns the leader:</p><pre class="programlisting">
    Leader leader = record.getLeader();
    </pre><p>The <code class="classname">org.marc4j.marc.Leader</code> class provides access to all the leader values. While the Leader represents mostly MARC structural information, some character positions provide bibliographic information. The method <code class="methodname">getTypeOfRecord()</code> for example identifies the type of material being catalogued, such as map, musical sound recording, or projected medium.</p><p>There are several methods available to retrieve variable fields. The <code class="methodname">getVariableFields()</code> method for example returns all variable fields as a <code class="classname">java.util.List</code>, but in most cases you will use methods that provide more control. The following method for example returns all control fields:</p><pre class="programlisting">
    // returns fields for tags 001 through 009
    List fields = record.getControlFields();
    </pre><p>And this method return all data fields:</p><pre class="programlisting">
    // returns fields for tags 010 through 999
    List fields = record.getDataFields();
    </pre><p>For control fields MARC4J does not provide you with the level of detail you might expect. You can retrieve the tag and the data, but to retrieve specific data elements at character positions you need to use some standard Java. This is because MARC4J is designed to handle different MARC formats like MARC 21 and UNIMARC. To retrieve the language of the item in a MARC 21 record, for example, you should do something like this:</p><pre class="programlisting">
    // get control field with tag 008
    ControlField field = (ControlField) record.getVariableField("008");
    String data = field.getData();

    // the three-character MARC language code takes character positions 35-37
    String lang = data.substring(35,38);
    System.out.println("Language: " + lang);
     </pre><p>For our example record this would produce the following output: </p><pre class="programlisting">
    Language: eng  
     </pre><p>For the control number field MARC4J provides two specific methods. Use <code class="methodname">getControlNumberField()</code> to retrieve the control number object for tag 001, or use <code class="methodname">getControlNumber()</code> to retieve the control number as a <code class="classname">String</code> object.</p><p>The previous example also showed how you can retrieve variable fields for a given tag using the <code class="methodname">getVariableField(String tag)</code> method. If you want to retrieve specific fields you can use one of the following methods:</p><pre class="programlisting">
    // get the first field occurence for a given tag
    DataField title = (DataField) record.getVariableField("245");
    
    // get all occurences for a particular tag
    List subjects = record.getVariableFields("650");
    
    // get all occurences for a given list of tags
    String[] tags = {"010", "100", "245", "250", "260", "300"};
    List fields = record.getVariableFields(tags);
     </pre><p>These methods return a <code class="classname">org.marc4j.marc.VariableField</code>, so if you need to access specific methods, like <code class="methodname">getData()</code> for a control field, you need to cast the variable field to a <code class="classname">org.marc4j.marc.ControlField</code> or <code class="classname">org.marc4j.marc.DataField</code>. A <code class="classname">DataField</code> is slightly more complex than a control field since it has indicators and subfields. The following example retrieves the title information field and writes the tag, indicators and subfields to standard output:</p><pre class="programlisting">
    DataField field = (DataField) record.getVariableField("245");
    String tag = field.getTag();
    char ind1 = field.getIndicator1();
    char ind2 = field.getIndicator2();

    System.out.println("Tag: " + tag + " Indicator 1: " + ind1 + " Indicator 2: " + ind2);

    List subfields = field.getSubfields();
    Iterator i = subfields.iterator();

    while (i.hasNext()) {
        Subfield subfield = (Subfield) i.next();
	char code = subfield.getCode();
	String data = subfield.getData();

	System.out.println("Subfield code: " + code + " Data element: " + data);
    }
     </pre><p>For our record for <span class="emphasis"><em>Summerland</em></span> by Michael Chabon this would produce the following output:</p><pre class="programlisting">
    Tag: 245 Indicator 1: 1 Indicator 2: 0
    Subfield code: a Data element: Summerland /
    Subfield code: c Data element: Michael Chabon.
     </pre><p>The <code class="classname">org.marc4j.marc.DataField</code> class also provides some methods to retrieve specific subfields:</p><pre class="programlisting">
    // retrieve the first occurrence of subfield with code 'a'
    Subfield subfield = field.getSubfield('a');

    // retrieve all subfields with code 'a'
    List subfields = field.getSubfields('a');
     </pre><p>The following code snippet uses <code class="methodname">getSubfield(char code)</code> to retrieve the title proper. It then removes the non-sort characters:</p><pre class="programlisting">
    // get data field 245
    DataField field = (DataField) record.getVariableField("245");

    // get indicator as int value
    char ind2 = field.getIndicator2();
    
    // get the title proper
    Subfield subfield = field.getSubfield('a');
    String title = subfield.getData();

    // remove the non sorting characters
    int nonSort = Character.digit(c, 10);
    title = title.substring(nonSort);
     </pre><p>In addition to retrieving fields by tag name, you can also retrieve fields by data element values using the <code class="methodname">find()</code> methods. The search capabilities are limited, but they can be useful when processing records. The following code snippet provides some basic examples:</p><pre class="programlisting">
    // find any field containing 'Chabon'
    List fields = record.find("Chabon");
    
    // find 'Summerland' in a title field
    List fields = record.find("245", "Summerland");
    
    // find 'Graham, Paul' in main or added entries for a personal name:
    String tags = {"100", "600"};
    List fields = record.find(tags, "Graham, Paul")  
     </pre><p>The find method is also useful if you want to retrieve records that meet certain criteria, such as a specific control number, title words or a particular publisher or subject. The example below checks if the cataloging agency is DLC. It also shows how you can extend the find capailities to specific subfields, a feature not directly available in MARC4J, since it is easy to accomplish using the record object model together with the standard Java API's.</p><div class="example"><a name="N1012A"></a><p class="title"><b>Example&nbsp;3.&nbsp;A check agency program</b></p><pre class="programlisting">
    import java.io.InputStream;
    import java.io.FileInputStream;
    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.marc.Record;
    import org.marc4j.marc.DataField;
    import org.marc4j.marc.Subfield;
    import java.util.List;

    public class CheckAgencyExample {

        public static void main(String args[]) throws Exception {

            InputStream input = new FileInputStream("file.mrc");
	    MarcReader reader = new MarcStreamReader(input);
	    while (reader.hasNext()) {
    	        Record record = reader.next();
    	
		// check if the cataloging agency is DLC
		List result = record.find("040", "DLC");
		if (result.size() &gt; 0)
		    System.out.println("Agency for this record is DLC");
    	
    	        // there is no specific find for a specific subfield
    	        // so to check if it is the orignal cataloging agency
    	        DataField field = (DataField)result.get(0);
		String agency = field.getSubfield('a').getData();
		if (agency.matches("DLC"))
                    System.out.println("DLC is the original agency");    	    	
            }
        }

    }
     </pre></div><p>By using <code class="methodname">find()</code> you can also implement a kind of search and replace to batch update records that meet certain criteria. You can use Java regular expressions in <code class="methodname">find()</code> methods. Check the <span class="package">java.util.regex</span> package for more information and examples.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1013B"></a>Reading MARC XML data</h2></div></div><div></div></div><p>Until now we have been processing MARC data in ISO 2709 format, but you can also read MARC data in <a href="http://www.loc.gov/standards/marcxml/" target="_top">MARC XML</a> format. The MARC 21 XML schema was published in June 2002 by the Library of Congress to encourage the standardization of MARC 21 records in the XML environment. The schema was developed in collaboration with OCLC and RLG after a survey of schema's that where used in various projects trying to bridge the gap between MARC and XML, including a MARC XML schema developed by the OAI (Open Archives Initiative) and the one used in early versions of MARC4J, published as James (Java MARC Events). The MARC XML schema is specified in a W3C XML Schema and provides lossless conversion between MARC ISO 2709 and MARC XML. As a consequence of the lossless conversion, information in a MARC XML record enables recreation of a MARC ISO 2709 record without loss of data. This is the record for <span class="emphasis"><em>Summerland</em></span> by Michael Chabon in MARC XML:</p><div class="example"><a name="N10147"></a><p class="title"><b>Example&nbsp;4.&nbsp;MARC XML record</b></p><pre class="programlisting">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;collection xmlns="http://www.loc.gov/MARC21/slim"&gt;
  &lt;record&gt;
    &lt;leader&gt;00714cam a2200205 a 4500&lt;/leader&gt;
    &lt;controlfield tag="001"&gt;12883376&lt;/controlfield&gt;
    &lt;controlfield tag="005"&gt;20030616111422.0&lt;/controlfield&gt;
    &lt;controlfield tag="008"&gt;020805s2002    nyu    j      000 1 eng  &lt;/controlfield&gt;
    &lt;datafield tag="020" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;0786808772&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="020" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;0786816155 (pbk.)&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="040" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;DLC&lt;/subfield&gt;
      &lt;subfield code="c"&gt;DLC&lt;/subfield&gt;
      &lt;subfield code="d"&gt;DLC&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="100" ind1="1" ind2=" "&gt;
      &lt;subfield code="a"&gt;Chabon, Michael.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="245" ind1="1" ind2="0"&gt;
      &lt;subfield code="a"&gt;Summerland /&lt;/subfield&gt;
      &lt;subfield code="c"&gt;Michael Chabon.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="250" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;1st ed.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="260" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;New York :&lt;/subfield&gt;
      &lt;subfield code="b"&gt;Miramax Books/Hyperion Books for Children,&lt;/subfield&gt;
      &lt;subfield code="c"&gt;c2002.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="300" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;500 p. ;&lt;/subfield&gt;
      &lt;subfield code="c"&gt;22 cm.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="520" ind1=" " ind2=" "&gt;
      &lt;subfield code="a"&gt;Ethan Feld, the worst baseball player in the history of the game, finds himself 
recruited by a 100-year-old scout to help a band of fairies triumph over an ancient enemy.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="650" ind1=" " ind2="1"&gt;
      &lt;subfield code="a"&gt;Fantasy.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="650" ind1=" " ind2="1"&gt;
      &lt;subfield code="a"&gt;Baseball&lt;/subfield&gt;
      &lt;subfield code="v"&gt;Fiction.&lt;/subfield&gt;
    &lt;/datafield&gt;
    &lt;datafield tag="650" ind1=" " ind2="1"&gt;
      &lt;subfield code="a"&gt;Magic&lt;/subfield&gt;
      &lt;subfield code="v"&gt;Fiction.&lt;/subfield&gt;
    &lt;/datafield&gt;
  &lt;/record&gt;
&lt;/collection&gt;
     </pre></div><p>Reading MARC XML data is not different from reading MARC data in ISO 2709 format, but MARC XML reader provides some additional XML related features. Here is our first exampe, but now reading a file containing records in MARC XML format:</p><div class="example"><a name="N1014E"></a><p class="title"><b>Example&nbsp;5.&nbsp;Reading MARC XML</b></p><pre class="programlisting">
    import org.marc4j.MarcReader;
    import org.marc4j.MarcXmlReader;
    import org.marc4j.marc.Record;
    import java.io.InputStream;
    import java.io.FileInputStream;

    public class ReadMarcXmlExample {

        public static void main(String args[]) throws Exception {

	    InputStream in = new FileInputStream("summerland.xml");
            MarcReader reader = new MarcXmlReader(in);
            while (reader.hasNext()) {
                 Record record = reader.next();
                 System.out.println(record.toString());
            }    

        }

    }
      </pre></div><p>When you compile and run this program it will write each record in tagged display format to standard output:</p><div class="example"><a name="N10156"></a><p class="title"><b>Example&nbsp;6.&nbsp;Output from MARC XML in tagged display format</b></p><pre class="programlisting">
    LEADER 00714cam a2200205 a 4500
    001 12883376
    005 20030616111422.0
    008 020805s2002    nyu    j      000 1 eng
    020   $a0786808772
    020   $a0786816155 (pbk.)
    040   $aDLC$cDLC$dDLC
    100 1 $aChabon, Michael.
    245 10$aSummerland /$cMichael Chabon.
    250   $a1st ed.
    260   $aNew York :$bMiramax Books/Hyperion Books for Children,$cc2002.
    300   $a500 p. ;$c22 cm.
    520   $aEthan Feld, the worst baseball player in the history of the game, finds
    himself recruited by a 100-year-old scout to help a band of fairies triumph over
    an ancient enemy.
    650  1$aFantasy.
    650  1$aBaseball$vFiction.
    650  1$aMagic$vFiction.
      </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1015B"></a>Reading MODS data</h2></div></div><div></div></div><p>Now let's look at the specific XML related features of <code class="classname">org.marc4j.MarcXmlreader</code>. Probably the most interesting feature is that you can pre-pocess the input using a stylesheet. This makes it possible to create a stylesheet in XSLT that transforms some kind of XML data to MARC XML. You can then process the result like you would do with MARC XML or MARC in ISO 2709 format. The Library of congress, for example, provides a stylesheet that transforms MODS (Metadata Object Description Schema) to MARC XML. MODS is a schema for a bibliographic element set that is maintained by The Library of Congress. The schema provides a subset of the MARC standard, but an advantage to the MARC XML format is that it uses language-based tags rather than numeric ones. A bibliographic record for <span class="emphasis"><em>Summerland</em></span> by Michael Chabon in MODS looks like this:</p><div class="example"><a name="N10166"></a><p class="title"><b>Example&nbsp;7.&nbsp;MODS record</b></p><pre class="programlisting">

&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;modsCollection xmlns="http://www.loc.gov/mods/v3"&gt;
  &lt;mods version="3.0"&gt;
    &lt;titleInfo&gt;
      &lt;title&gt;Summerland&lt;/title&gt;
    &lt;/titleInfo&gt;
    &lt;name type="personal"&gt;
      &lt;namePart&gt;Chabon, Michael.&lt;/namePart&gt;
      &lt;role&gt;
	&lt;roleTerm authority="marcrelator" type="text"&gt;creator&lt;/roleTerm&gt;
      &lt;/role&gt;
    &lt;/name&gt;
    &lt;typeOfResource&gt;text&lt;/typeOfResource&gt;
    &lt;originInfo&gt;
      &lt;place&gt;
	&lt;placeTerm type="code" authority="marccountry"&gt;nyu&lt;/placeTerm&gt;
      &lt;/place&gt;
      &lt;place&gt;
	&lt;placeTerm type="text"&gt;New York&lt;/placeTerm&gt;
      &lt;/place&gt;
      &lt;publisher&gt;Miramax Books/Hyperion Books for Children&lt;/publisher&gt;
      &lt;dateIssued&gt;c2002&lt;/dateIssued&gt;
      &lt;dateIssued encoding="marc"&gt;2002&lt;/dateIssued&gt;
      &lt;edition&gt;1st ed.&lt;/edition&gt;
      &lt;issuance&gt;monographic&lt;/issuance&gt;
    &lt;/originInfo&gt;
    &lt;language&gt;
      &lt;languageTerm authority="iso639-2b" type="code"&gt;eng&lt;/languageTerm&gt;
    &lt;/language&gt;
    &lt;physicalDescription&gt;
      &lt;form authority="marcform"&gt;print&lt;/form&gt;
      &lt;extent&gt;500 p. ; 22 cm.&lt;/extent&gt;
    &lt;/physicalDescription&gt;
    &lt;abstract&gt;Ethan Feld, the worst baseball player in the history of the game, finds 
himself recruited by a 100-year-old scout to help a band of fairies triumph over 
an ancient enemy.&lt;/abstract&gt;
    &lt;targetAudience authority="marctarget"&gt;juvenile&lt;/targetAudience&gt;
    &lt;note type="statement of responsibility"&gt;Michael Chabon.&lt;/note&gt;
    &lt;subject&gt;
      &lt;topic&gt;Fantasy&lt;/topic&gt;
    &lt;/subject&gt;
    &lt;subject&gt;
      &lt;topic&gt;Baseball&lt;/topic&gt;
      &lt;topic&gt;Fiction&lt;/topic&gt;
    &lt;/subject&gt;
    &lt;subject&gt;
      &lt;topic&gt;Magic&lt;/topic&gt;
      &lt;topic&gt;Fiction&lt;/topic&gt;
    &lt;/subject&gt;
    &lt;identifier type="isbn"&gt;0786808772&lt;/identifier&gt;
    &lt;identifier type="isbn"&gt;0786816155 (pbk.)&lt;/identifier&gt;
    &lt;recordInfo&gt;
      &lt;recordContentSource authority="marcorg"&gt;DLC&lt;/recordContentSource&gt;
      &lt;recordCreationDate encoding="marc"&gt;020805&lt;/recordCreationDate&gt;
      &lt;recordChangeDate encoding="iso8601"&gt;20030616111422.0&lt;/recordChangeDate&gt;
      &lt;recordIdentifier&gt;12883376&lt;/recordIdentifier&gt;
    &lt;/recordInfo&gt;
  &lt;/mods&gt;
&lt;/modsCollection&gt;

      </pre></div><p>By using a <a href="http://www.loc.gov/standards/marcxml/xslt/MODS2MARC21slim.xsl" target="_top">stylesheet</a> available from The Library of Congress you can process the bibliographic information contained in a collection of MODS records as MARC data:</p><div class="example"><a name="N10171"></a><p class="title"><b>Example&nbsp;8.&nbsp;Reading MODS data</b></p><pre class="programlisting">
    import org.marc4j.MarcReader;
    import org.marc4j.MarcXmlReader;
    import org.marc4j.marc.Record;
    import java.io.InputStream;
    import java.io.FileInputStream;

    public class ModsToMarc21Example {

        public static void main(String args[]) throws Exception {

	    InputStream in = new FileInputStream("mods.xml");
            MarcXmlReader reader = new MarcXmlReader(in, "http://www.loc.gov/standards/marcxml/xslt/MODS2MARC21slim.xsl");
            while (reader.hasNext()) {
                 Record record = reader.next();
                 System.out.println(record.toString());
            }    

        }

    }
      </pre></div><p>When you compile and run this program it will write each record in tagged display format to standard output:</p><div class="example"><a name="N10179"></a><p class="title"><b>Example&nbsp;9.&nbsp;Output from MODS data in tagged format</b></p><pre class="programlisting">
    LEADER 00000nam  2200000uu 4500
    001 12883376
    005 20030616111422.0
    008 020805|2002    nyu||||j |||||||||||eng||
    020   $a0786808772
    020   $a0786816155 (pbk.)
    040   $aDLC
    100 1 $aChabon, Michael.$ecreator
    245 10$aSummerland$cMichael Chabon.
    250   $a1st ed.
    260   $aNew York$bMiramax Books/Hyperion Books for Children$cc2002$c2002
    300   $a500 p. ; 22 cm.
    520   $aEthan Feld, the worst baseball player in the history of the game, finds 
    himself recruited by a 100-year-old scout to help a band of fairies triumph over 
    an ancient enemy.
    650 1 $aFantasy
    650 1 $aBaseball$xFiction
    650 1 $aMagic$xFiction
      </pre></div><p>The stylesheet first transforms the MODS record to MARC XML and the XSLT output is then parsed by the <code class="classname">org.marc4j.MarcXmlReader</code>.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10183"></a>Writing MARC data</h2></div></div><div></div></div><p>For writing MARC data MARC4J provides a <code class="classname">org.marc4j.MarcWriter</code> interface. This interfaces provides two important methods:</p><div class="variablelist"><dl><dt><span class="term"><code class="methodname">write(Record record)</code></span></dt><dd><p>Writes a single <code class="classname">org.marc4j.marc.Record</code> to the output stream.</p></dd><dt><span class="term"><code class="methodname">close()</code></span></dt><dd><p>Closes the writer.</p></dd></dl></div><p>Let's look at an example. The following program reads the record for <span class="emphasis"><em>Summerland</em></span> and writes the same record back in ISO 2709 format:</p><div class="example"><a name="N101A2"></a><p class="title"><b>Example&nbsp;10.&nbsp;Write MARC in ISO 2709</b></p><pre class="programlisting">
    import java.io.InputStream;
    import java.io.FileInputStream;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcStreamWriter;
    import org.marc4j.MarcWriter;
    import org.marc4j.marc.Record;

    public class WriteMarcExample {

        public static void main(String args[]) throws Exception {

            InputStream input = new FileInputStream("summerland.mrc");

            MarcReader reader = new MarcStreamReader(input);
	    MarcWriter writer = new MarcStreamWriter(System.out);
	    while (reader.hasNext()) {
                Record record = reader.next();
                writer.write(record);
            }
            writer.close();
        }
    }
      </pre></div><p>Make sure that you close the <code class="classname">MarcWriter</code> using the <code class="methodname">close()</code> method.</p><p>To write the same record as MARC XML:</p><div class="example"><a name="N101B1"></a><p class="title"><b>Example&nbsp;11.&nbsp;Write MARC in MARC XML format</b></p><pre class="programlisting">
    import java.io.InputStream;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcWriter;
    import org.marc4j.MarcXmlWriter;
    import org.marc4j.converter.impl.AnselToUnicode;
    import org.marc4j.marc.Record;

    public class Marc2MarcXmlExample {

        public static void main(String args[]) throws Exception {

            InputStream input = new FileInputStream("summerland.mrc");

	    MarcReader reader = new MarcStreamReader(input);
	    MarcWriter writer = new MarcXmlWriter(System.out, true);

	    while (reader.hasNext()) {
	        Record record = reader.next();
		writer.write(record);
            }
            writer.close();
        }
    }
      </pre></div><p>Of course you can also write MARC XML data to MARC in ISO 2709 format by using a <code class="classname">org.marc4j.MarcXmlReader</code> to read MARC XML data and a <code class="classname">org.marc4j.MarcStreamWriter</code> to write MARC data in ISO 2709 format.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N101BE"></a>Perform character conversions</h2></div></div><div></div></div><p>When serializing <code class="classname">Record</code> objects you can perform character conversions. This feature is especially important when you convert MARC data between ISO 2709 and MARC XML formats. Most MARC formats use specific character sets and MARC4J is able to convert some of them to UCS/Unicode and back. Converters are available for the following encodings:</p><table summary="Simple list" border="0" class="simplelist"><tr><td>MARC-8</td></tr><tr><td>ISO 5426</td></tr><tr><td>ISO 6937</td></tr></table><p>Using the converters is not difficult, but there are some things to remember. MARC4J reads and writes ISO 2709 records as binary data, but data elements in control fields and subfields are converted to <code class="classname">String</code> values. When Java converts a byte array to a <code class="classname">String</code> it needs a character encoding. Java can use a default character encoding, but this might not always be the right encoding to use. Therefore both <code class="classname">org.marc4j.MarcReader</code> and <code class="classname">org.marc4j.MarWriter</code> implementations provide you with the ability to register a character encoding when constructing a new instance. If you do not provide a character encoding the following defaults are used:</p><div class="table"><a name="N101DB"></a><p class="title"><b>Table&nbsp;1.&nbsp;Character encodings in MARC4J</b></p><table summary="Character encodings in MARC4J" border="1"><colgroup><col><col></colgroup><thead><tr><th valign="top">Class name</th><th>Encoding</th></tr></thead><tbody><tr><td valign="top"><code class="classname">org.marc4j.MarcStreamReader</code></td><td>
	      <p>Tries to detect the encoding from the <code class="classname">org.marc4j.marc.Leader</code> by reading the character encoding scheme in the leader using the <code class="methodname">getCharEncoding()</code> method. You can override the value when instantiating a <code class="classname">MarcStreamReader</code>:</p>
	      <pre class="programlisting">
    MarcReader reader = new MarcStreamReader(input, "UTF8");
	      </pre>
	    </td></tr><tr><td valign="top"><code class="classname">org.marc4j.MarcXmlReader</code></td><td>
	      <p>Relies on the underlying XML parser implementation. Normally you would provide the encoding in the XML declaration of the input file:</p>
	      <pre class="programlisting">
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
	      </pre>
	    </td></tr><tr><td valign="top"><code class="classname">org.marc4j.MarcStreamWriter</code></td><td>
	      <p>By default uses ISO 8859-1 (Latin 1) as 8-bit character set alternative since encodings like MARC-8 are not supported by Java. You can override the value when instantiating a <code class="classname">MarcStreamWriter</code>:</p>
	      <pre class="programlisting">
    MarcWriter writer = new MarcStreamWriter(ouput, "UTF8");
	      </pre>
	    </td></tr><tr><td valign="top"><code class="classname">org.marc4j.MarcXmlWriter</code></td><td>
	      <p>Uses UTF-8 by default. You can override the value when instantiating a <code class="classname">MarcXmlWriter</code>:</p>
	      <pre class="programlisting">
    MarcWriter writer = new MarcXMLWriter(ouput, "UTF8");
	      </pre>
	      <p>For the encoding in the XML declaration MARC4J relies on the underlying parser.</p>
</td></tr></tbody></table></div><p>Check the Java <a href="http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html" target="_top">supported encodings</a> for the canonical name to use for a specific encoding.</p><p>Now let's look at some examples. The following program reads ISO 2709 records using the default encoding and writes the records in ISO 2709 performing a MARC-8 to UCS/Unicode conversion:</p><div class="example"><a name="N10236"></a><p class="title"><b>Example&nbsp;12.&nbsp;Write MARC in ISO 2709</b></p><pre class="programlisting">
    import java.io.InputStream;
    import java.io.FileInputStream;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcStreamWriter;
    import org.marc4j.MarcWriter;
    import org.marc4j.marc.Record;

    public class Marc8ToUnicodeExample {

        public static void main(String args[]) throws Exception {

            InputStream input = new FileInputStream("summerland.mrc");

            MarcReader reader = new MarcStreamReader(input);
	    MarcWriter writer = new MarcStreamWriter(System.out, "UTF8");

            AnselToUnicode converter = new AnselToUnicode();
            writer.setConverter(converter);

	    while (reader.hasNext()) {
                Record record = reader.next();
                writer.write(record);
            }
            writer.close();
        }
    }
      </pre></div><p>Since <code class="classname">MarcStreamWriter</code> uses the Latin-1 character encoding by default, we instantiate the writer with the UTF-8 character encoding.</p><p>To convert ISO 2709 in MARC-8 to MARC XML in UCS/Unicode:</p><div class="example"><a name="N10242"></a><p class="title"><b>Example&nbsp;13.&nbsp;Write MARC in ISO 2709</b></p><pre class="programlisting">
    import java.io.InputStream;
    import java.io.FileInputStream;

    import java.io.OutputStream;
    import java.io.FileOutputStream;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcStreamWriter;
    import org.marc4j.MarcWriter;
    import org.marc4j.marc.Record;

    public class Marc8ToMarcXmlExample {

        public static void main(String args[]) throws Exception {

            InputStream input = new FileInputStream("summerland.mrc");

            OutputStream out = new FileOutputStream("summerland.xml");

            MarcReader reader = new MarcStreamReader(input);
	    MarcWriter writer = new MarcXmlWriter(out, true);

            AnselToUnicode converter = new AnselToUnicode();
            writer.setConverter(converter);

	    while (reader.hasNext()) {
                Record record = reader.next();
                writer.write(record);
            }
            writer.close();
        }
    }
      </pre></div><p>In addition to using a character converter, you can perform Unicode normalization. This is for example not done by the MARC-8 to UCS/Unicode converter. With Unicode normalization text is transformed into the canonical composed form. For example "a&acute;bc" is normalized to "&aacute;bc". To perform normalization set Unicode normalization to true:</p><pre class="programlisting">
    MarcXmlWriter writer = new MarcXmlWriter(out, true);

    AnselToUnicode converter = new AnselToUnicode();
    writer.setConverter(converter);

    writer.setUnicodeNormalization(true);
    </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note that it's not garanteed to work if you try to convert normalized Unicode back to MARC-8.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N1024E"></a>Advanced MARC XML features</h2></div></div><div></div></div><p>You can write the output of <code class="classname">org.marc4j.MarcXmlWriter</code> to an implementation of the <code class="classname">javax.xml.transform.Result</code> interface. This enables you to tightly integrate MARC4J with your XML application. Below are just some examples of what you can do using the <code class="classname">Result</code> interface. If you want to know more about Java and XML there are numerous books and tutorials available. A good tutorial is <a href="http://www.cafeconleche.org/books/xmljava/" target="_top">Processing XML with Java</a> by Elliotte Rusty Harold.</p><p>The <code class="classname">org.marc4j.MarcXmlWriter</code> class provides very basic formatting options. If you need more advanced formatting options, you can use a <code class="classname">SAXResult</code> containing a <code class="classname">ContentHandler</code> derived from a dedicated XML serializer. The following example uses <code class="classname">org.apache.xml.serialize.XMLSerializer</code> to write MARC records to XML using MARC-8 to UCS/Unicode conversion and Unicode normalization:</p><div class="example"><a name="N1026E"></a><p class="title"><b>Example&nbsp;14.&nbsp;Formatting output with the Xerces serializer</b></p><pre class="programlisting">
    import java.io.InputStream;

    import javax.xml.transform.Result;
    import javax.xml.transform.sax.SAXResult;

    import org.apache.xml.serialize.OutputFormat;
    import org.apache.xml.serialize.XMLSerializer;
    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcXmlWriter;
    import org.marc4j.converter.impl.AnselToUnicode;
    import org.marc4j.marc.Record;

    public class XercesSerializerExample {

        public static void main(String args[]) throws Exception {

	    InputStream input = new FileInputStream("summerland.mrc");

            MarcReader reader = new MarcStreamReader(input);

	    OutputFormat format = new OutputFormat("xml", "UTF-8", true);

	    XMLSerializer serializer = new XMLSerializer(System.out, format);
	    Result result = new SAXResult(serializer.asContentHandler());

	    MarcXmlWriter writer = new MarcXmlWriter(result);
	    writer.setConverter(new AnselToUnicode());

	    while (reader.hasNext()) {
                Record record = reader.next();
                writer.write(record);
            }
            writer.close();

        }
    }  
      </pre></div><p>You can post-process the result using a <code class="classname">Source</code> object pointing to a stylesheet resource and a Result object to hold the transformation result tree. The example below converts MARC to MARCXML and transforms the result tree to MODS using the <a href="http://www.loc.gov/standards/mods/v3/MARC21slim2MODS3.xsl" target="_top">stylesheet</a> provided by The Library of Congress:</p><div class="example"><a name="N1027C"></a><p class="title"><b>Example&nbsp;15.&nbsp;Write MODS data</b></p><pre class="programlisting">
    import java.io.InputStream;

    import javax.xml.transform.Result;
    import javax.xml.transform.Source;
    import javax.xml.transform.stream.StreamResult;
    import javax.xml.transform.stream.StreamSource;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcXmlWriter;
    import org.marc4j.converter.impl.AnselToUnicode;
    import org.marc4j.marc.Record;

    public class Marc2ModsExample {

        public static void main(String args[]) throws Exception {

            String stylesheetUrl = "http://www.loc.gov/standards/mods/v3/MARC21slim2MODS3.xsl";
	    Source stylesheet = new StreamSource(stylesheetUrl);

	    Result result = new StreamResult(System.out);

	    InputStream input = new FileInputStream("summerland.mrc");

            MarcReader reader = new MarcStreamReader(input);

	    MarcXmlWriter writer = new MarcXmlWriter(result, stylesheet);
	    writer.setConverter(new AnselToUnicode());

	    while (reader.hasNext()) {
                Record record = (Record) reader.next();
                writer.write(record);
            }
            writer.close();
        }
    }
      </pre></div><p>It is also possible to write the result into a DOM Node. You can then use the DOM document for further processing in your XML applicaiton, for example to embed MARC XML or MODS data in other XML documents.</p><div class="example"><a name="N10283"></a><p class="title"><b>Example&nbsp;16.&nbsp;Write output to a DOM tree</b></p><pre class="programlisting">
    import java.io.InputStream;

    import javax.xml.transform.dom.DOMResult;

    import org.marc4j.MarcReader;
    import org.marc4j.MarcStreamReader;
    import org.marc4j.MarcXmlWriter;
    import org.marc4j.converter.impl.AnselToUnicode;
    import org.marc4j.marc.Record;
    import org.w3c.dom.Document;

    public class Marc2DomExample {

        public static void main(String args[]) throws Exception {

	    InputStream input = new FileInputStream("summerland.mrc");

	    MarcReader reader = new MarcStreamReader(input);

	    DOMResult result = new DOMResult();

	    MarcXmlWriter writer = new MarcXmlWriter(result);
	    writer.setConverter(new AnselToUnicode());

	    while (reader.hasNext()) {
                Record record = (Record) reader.next();
                writer.write(record);
	    }
            writer.close();

            Document doc = (Document) result.getNode();

        }
    }
      </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10288"></a>Summary</h2></div></div><div></div></div><p>This tutorial covers a lot of features of MARC4J. If this tutorial didn't show you how to do what you need to do, try looking in the Javadoc that is included in the MARC4J distribution or send an e-mail to the <a href="http://marc4j.tigris.org/servlets/ProjectMailingListList" target="_top">mailing-list</a> for MARC4J users. Most of the samples in this tutorial are available in the <code class="classname">org.marc4j.samples</code> package.</p><p>Lat updated: $Date: 2006/08/04 13:25:06 $</p></div></div></body></html>