src/org/marc4j/marc/package.html

   1 <html>\r
   2   <head>\r
   3     <title>org.marc4j.marc</title>\r
   4   </head>\r
   5   <!--\r
   6   /*\r
   7    * Copyright (C) 2004-2006 Bas Peters. All rights reserved.\r
   8    *\r
   9    */\r
  10   -->\r
  11   <body>\r
  12     <p>Interfaces for the record object model.</p>\r
  13     <p>The goal of the <code>org.marc4j.marc</code> package is to provide a clean and simple to use interface to \r
  14     create, store and edit MARC records or parts of records as objects. \r
  15     See the examples below to get started using the object model.</p>\r
  16     <h3>Reading records</h3>\r
  17     <p>The {@link org.marc4j.marc.Record}&nbsp;interface provides access to the \r
  18     leader and variable fields for each record returned by the {@link org.marc4j.MarcReader}&nbsp;implementation.</p>\r
  19     <p>The following example retrieves all control fields (tags 001 through 009):<p>\r
  20     <pre>\r
  21     List fields = record.getControlFields();\r
  22     </pre>\r
  23     <p>This method retuns the fields as a {@link java.util.List}, thus enabling the use of the standard Java collections \r
  24     framework to iterate over collections of records, fields or subfields. \r
  25     The following code snippet prints the tag and data for each control field to standard output:</p>\r
  26     <pre>\r
  27     Iterator i = fields.iterator();\r
  28     while (i.hasNext()) {\r
  29         ControlField field = (ControlField) i.next();\r
  30         System.out.println("Tag: " + field.getTag() + " Data: " + field.getData());\r
  31     }\r
  32     </pre>\r
  33     <p>The <code>getDataFields()</code> method returns all data fields (tags 010 through 999). \r
  34     An {@link org.marc4j.marc.DataField}&nbsp;provides access to the tag, the indicators and the subfields.\r
  35     For example to write all the data field information to standard output:</p>\r
  36     <pre>\r
  37     List fields = record.getDataFields();\r
  38     Iterator i = fields.iterator();\r
  39     while (i.hasNext()) {\r
  40         DataField field = (ControlField) i.next();\r
  41         System.out.println("Tag: " + field.getTag() + " ind1: " + field.getIndicator1() + \r
  42             " ind2: " + field.getIndicator2());\r
  43         List subfields = field.getSubfields();\r
  44         Iterator j = subfields.iterator();\r
  45         while (j.hasNext()) {\r
  46             Subfield subfield = (Subfield) j.next();\r
  47             System.out.println("Subfield code: " + subfield.getCode() + \r
  48                 "Data: " + subfield.getData());\r
  49         }\r
  50     }\r
  51     </pre>\r
  52     <p>If you want to retrieve specific fields you can use one of the following methods:</p>\r
  53     <pre>\r
  54     // get the first field occurence for a given tag\r
  55     DataField title = (DataField)record.getVariableField("245");\r
  56     \r
  57     // get all occurences for a particular tag\r
  58     List subjects = record.getVariableFields("650");\r
  59     \r
  60     // get all occurences for a given list of tags\r
  61     String[] tags = {"010", "100", "245", "250", "260", "300"};\r
  62     List fields = record.getVariableFields(tags);\r
  63     </pre>\r
  64     <p>In addition you can use simple searches using the <code>find()</code> methods \r
  65     to retrieve fields that meet certain criteria. The search capabilities are very \r
  66     limited, but they can be useful when processing records. The following code snippet \r
  67     provides some examples:</p>\r
  68     <pre>\r
  69     // find any field containing 'Chabon'\r
  70     List fields = record.find("Chabon");\r
  71     \r
  72     // find 'Summerland' in a title field\r
  73     List fields = record.find("245", "Summerland");\r
  74     \r
  75     // find 'Graham, Paul' in main or added entries for a personal name:\r
  76     String tags = {"100", "600"};\r
  77     List fields = record.find(tags, "Graham, Paul")  \r
  78     </pre>\r
  79     <p>The find method is also useful if you want to retrieve records that meet \r
  80     certain criteria, such as a specific control number, title words or a particular publisher \r
  81     or subject. The example below checks if the cataloging agency is DLC. The example also shows \r
  82     how you can extend the find capailities to specific subfields, a feature not directly available \r
  83     in MARC4J, since it is easy to accomplish using the record model together with the standard Java API's.</p>\r
  84     <pre>\r
  85     InputStream input = new FileInputStream("file.mrc");\r
  86     MarcReader reader = new MarcStreamReader(input);\r
  87     while (reader.hasNext()) {\r
  88         Record record = reader.next();\r
  89         \r
  90         // check if the cataloging agency is DLC\r
  91         List result = record.find("040", "DLC");\r
  92         if (result.size() > 0)\r
  93             System.out.println("Agency for this record is DLC");\r
  94         \r
  95         // there is no specific find for a specific subfield\r
  96         // so to check if it is the orignal cataloging agency\r
  97         DataField field = (DataField)result.get(0);\r
  98         String agency = field.getSubfield('a').getData();\r
  99         if (agency.matches("DLC"))\r
 100             System.out.println("DLC is the original agency");           \r
 101         \r
 102     }\r
 103     </pre>\r
 104     <p>By using <code>find()</code> you can also implement a kind of search and replace to batch \r
 105     update records that meet certain criteria. You can use Java regular expressions in <code>find()</code> methods. \r
 106     Check the \r
 107     <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/package-summary.html">java.util.regex</a> \r
 108     package for more information and examples.</p>\r
 109     <h3>Creating or updating records</h3>\r
 110         <p>You can also create or update records using the {@link org.marc4j.marc.MarcFactory}. For example:</p>\r
 111         <pre>\r
 112     // create a factory instance\r
 113     MarcFactory factory = MarcFactory.newInstance();\r
 114         \r
 115     // create a record with leader\r
 116     Record record = factory.newRecord("00000cam a2200000 a 4500");\r
 117         \r
 118     // add a control field\r
 119     record.addVariableField(factory.newControlField("001", "12883376"));\r
 120         \r
 121     // add a data field\r
 122     DataField df = factory.newDataField("245", '1', '0');\r
 123     df.addSubfield(factory.newSubfield('a', "Summerland /"));\r
 124     df.addSubfield(factory.newSubfield('c', "Michael Chabon."));\r
 125     record.addVariableField(df);\r
 126     </pre>\r
 127         <p>You can use a {@link org.marc4j.MarcWriter} implementation to serialize your records for example to MARC or MARC XML.\r
 128         The code snippet below writes a single record in MARC format to standard output:</p>\r
 129         <pre>\r
 130     MarcWriter writer = new MarcStreamWriter(System.out);\r
 131     writer.write(record);\r
 132     writer.close(); \r
 133     </pre>\r
 134     <p>Check the Javadoc for {@link org.marc4j.MarcStreamWriter}&nbsp;and {@link org.marc4j.MarcXmlWriter}&nbsp;for more information.</p>\r
 135   </body>\r
 136 </html>\r