CMX API ver.0.21チュートリアル
第7回「独自フォーマットを定義する」

北原 鉄朗（JST CrestMuse／関西学院大学理工学研究科）
2007年10月19日

はじめに

例題：my-address-book-xml

単純な例として，音楽からいったん離れて，第3回で架空のXMLフォーマットとして取り上げたmy-address-book-xmlを取り上げましょう．my-address-book-xmlは，次のような形をしていました．

  <my-address-book-xml>
    <person>
      <name>Tetsuro Kitahara</name>
      <address>XX, YY, Osaka, Japan</address>
    </person>
  </my-address-book-xml>

DTDファイルを書く

まず，このXML形式の定義を表すDTDを書きましょう．ここではDTDの説明は省略しますが，このXML形式に対応するDTDは次のようになります．

<!ELEMENT my-address-book-xml (person*) >
<!ELEMENT person (name, address) >
<!ELEMENT name (#PCDATA) >
<!ELEMENT address (#PCDATA) >

  <?xml version="1.0" ?>
  <!DOCTYPE my-address-book-xml SYSTEM "my-address-book.dtd" >
  <my-address-book-xml>
    <person>
      <name>Tetsuro Kitahara</name>
      <address>XX, YY, Osaka, Japan</address>
    </person>
  </my-address-book-xml>

ファイルラッパクラスを書く

次に，ファイルラッパクラスを書きましょう．これはCMXFileWrapperクラスを継承して作ります．

import jp.crestmuse.cmx.filewrappers.*;

public class MyAddressBookWrapper extends CMXFileWrapper {

}

コマンドから自作のファイルラッパクラスを利用する

すでに何度か述べてきたとおり，コマンドはCMXCommandクラスを継承して定義します．CMXCommandクラスはXMLドキュメントを読み込む処理はすでに書いてあって，自作のクラスでは，読み込んだ後の処理だけを書けばよいようになっています．ファイルから読み込んだXMLドキュメントは，ファイルラッパクラスと呼んでいる，CMXFileWrapperクラスのサブクラスのインスタンスとして渡されます．どのファイルラッパクラスをインスタンス化すべきかは，読み込んだXMLドキュメントのトップレベルタグで判断しています．たとえば，トップレベルタグがscore-partwiseであれば，これはMusicXMLですのでMusicXMLWrapperオブジェクトが生成されます．

自作のファイルラッパクラスを利用しようとすると，ここで問題が発生します．自作のXMLフォーマットのトップレベルタグ（ここではmy-address-book-xml）と自作のファイルラッパクラス（ここではMyAddressBookWrapper）とが結び付いていることは，CMXFileWrapperは知る由もないということです．実は，知る由はあるのです．CMXFileWrapperクラスにはaddClassTableというメソッドが用意されています．このメソッドを使うと，自作のXMLフォーマットのトップレベルタグと自作のファイルラッパクラスの組み合わせを登録することができます．次のようにします．

import jp.crestmuse.cmx.commands.*;
import jp.crestmuse.cmx.filewrappers.*;

public class MyAddressBookTest extends CMXCommand {
  protected void run() {
    // 処理内容を書く
  }

  public static void main(String[] args) {
    MyAddressBookTest t = new MyAddressBookTest();
    try {
      // ↓addClassTableを使って自作のXMLフォーマットとファイルラッパクラスを登録する
      CMXFileWrapper.addClassTable("my-address-book-xml", "MyAddressBookWrapper");
      t.start(args);
    } catch (Exception e) {
      t.showErrorMessage(e);
      System.exit(1);
    }
  }
}

上であげたXMLドキュメントのサンプルをファイルに保存して，このプログラムを実行してみてください．ファイル名だけ表示されて終わったら成功です．何か例外が投げられて止まったらDTDファイル，XMLファイル，プログラムのどれかが間違っているはずですので，丹念に見直してください．

自作のファイルラッパクラスをどこかのパッケージに置いてある場合は，パッケージ名もふくめた名前を指定してください．たとえば，MyAddressBookWrapperクラスがfoo.barというパッケージにあるなら，

CMXFileWrapper.addClassTable("my-address-book-xml", "foo.bar.MyAddressBookWrapper");

CMXFileWrapperクラスのaddClassTableメソッドが働いていることを確かめるため，ためしにそこの文をコメントアウトしてコンパイル・実行をしてみてください．コンパイルは通ると思いますが，実行すると

jp.crestmuse.cmx.filewrappers.InvalidFileTypeException

自作のファイルラッパクラスに自作のノードインターフェイスクラスを定義する

my-address-book-xmlは，person要素が並んでいる形になってますので，person要素を扱うノードインターフェイスとしてPersonクラスを作ってみましょう．これは，MusicXMLWrapperクラスにならってMyAddressBookWrapperクラスの内部クラスとして定義してみましょう．

import jp.crestmuse.cmx.filewrappers.*;
import org.w3c.dom.*;

public class MyAddressBookWrapper extends CMXFileWrapper {
  class Person extends NodeInterface {
    protected Person(Node node) {
      super(node);
    }
    protected String getSupportedNodeName() {
      return "person";
    }
  }
}

person要素の中にはname要素とaddress要素があるので，それぞれの中身（テキスト）を返すメソッドを作りましょう．指定した子要素のテキストを返すメソッドとしてgetChildTextというのがNodeInterfaceクラスにすでに用意されていますから，次のようにすればOKということになります．

import jp.crestmuse.cmx.filewrappers.*;
import org.w3c.dom.*;

public class MyAddressBookWrapper extends CMXFileWrapper {
  class Person extends NodeInterface {
    protected Person(Node node) {
      super(node);
    }
    protected String getSupportedNodeName() {
      return "person";
    }
    String name() {
      return getChildText("name");
    }
    String address() {
      return getChildText("address");
    }
  }
}

次に，person要素をすべて探索して各々に対応するPersonオブジェクトを返してくれるメソッドを書いてみましょう．名前をgetPersonListとしましょう．CMXFileWrapperクラスにselectNodeListというメソッドがあります．これはXPath式を指定してそれを満たす要素を返すというものです．XPathの詳細はwebや書籍で勉強していただくとして，/my-address-book-xml/personとすれば，my-address-book-xmlというトップレベルタグのすぐ下のperson要素の集合を返してくれます．このメソッドはNodeListオブジェクトが返ってきます．結局，getPersonListメソッドは次のようになります．

  Person[] getPersonList() {
    NodeList nl = selectNodeList("/my-address-book-xml/person");
    int length = nl.getLength();
    Person[] personlist = new Person[length];
    for (int i = 0; i < length; i++) {
      personlist[i] = new Person(nl.item(i));
    }
    return personlist;
  }

ちなみに，Personクラスやその中のいくつかのメソッドはいわゆるpackage privateになってますので，他のパッケージからも利用する可能性があるのでしたら，publicにする必要があります．

自作のノードインターフェイスを利用する

以上で一通りファイルラッパができあがったので，これを自作のコマンドから利用してみましょう．上で定義したMyAddressBookTestのrunメソッドを次のように書き換えてみましょう．

  protected void run() {
    MyAddressBookWrapper book = (MyAddressBookWrapper)indata();
    MyAddressBookWrapper.Person[] personlist = book.getPersonList();
    System.out.println("name\taddress");
    for (int i = 0; i < personlist.length; i++) {
      System.out.println(personlist[i].name() + "\t" + personlist[i].address());
    }
  }

CMXFileWrapperクラスの設計のはなし

ここでは，CMX APIの使いかたからちょっと離れて，CMXFileWrapperクラスがどういう風に設計されているかについて触れておきます．ここの内容は分からなくても使う分には支障はないので，興味のある方だけお読みください．

XMLフォーマットごとにファイルラッパクラス（CMXFileWrapperクラスのサブクラス）が用意され，CMXCommandクラスを通じてインスタンス化されるというのはすでにご存知と思います．CMXCommandクラスのソースコードを見ると，runAllメソッドの中に

    indata = readInputData(filename);

    return CMXFileWrapper.readfile(filename, this);

  public static CMXFileWrapper readfile(String filename, 
                                        CMXInitializer init) throws (省略) {
    initXMLProcessors();
    Document doc = builder.parse(new File(filename));
    String toptagname = doc.getDocumentElement().getTagName();
    CMXFileWrapper f = createInstance(toptagname);
    (中略)
    return f;
  }

このcreateInstanceメソッドはどのように組めばよいでしょうか．たとえば，トップレベルタグ名がscore-partwiseならMusicXMLWrapperオブジェクト，deviationならDeviationInstanceWrapperオブジェクト，MIDIFileならMIDIXMLWrapperオブジェクトを返すようにするには，どうしたらいいでしょうか．

すぐに思いつくのはif文で分岐する方法だと思います．たとえば，こんな感じです．

  private CMXFileWrapper createInstance(String toptagname) {
    if (toptagname.equals("score-partwise"))
      return new MusicXMLWrapper();
    else if (toptagname.equals("deviation"))
      return new DeviationInstanceWrapper();
    else if (toptagname.equals("MIDIFile"))
      return new MIDIXMLWrapper();
    else ...
  }

そこで，CMXFileWrapperではトップレベルタグ名とファイルラッパクラスをHashMapで管理しています．CMXFileWrapperクラスのcreateInstanceメソッドでは

  CMXFileWrapper f = 
    (CMXFileWrapper)CLASS_TABLE.get(toptagname).newInstance();

おわりに