jp.crestmuse.cmx.filewrappers
クラス CMXFileWrapper

java.lang.Object
  上位を拡張 jp.crestmuse.cmx.filewrappers.CMXFileWrapper
直系の既知のサブクラス:
DeviationInstanceWrapper, MIDIXMLWrapper, MusicXMLWrapper, SCCXMLWrapper

public abstract class CMXFileWrapper
extends java.lang.Object

The abstract class CMXFileWrapper is the common superclass of the classes that wrap XML documents; In other words, all XML documents in CrestMuseXML are handled via subclasses of this class. This class holds an XML document as a Document Object Model (DOM), and processes it using a separate XML parser. This DOM processing is encapsulated by methods provided by this class.

This requires an XML parser compliant with JAXP (Xerces is prefered) and an XSLT processor (only Xalan is accepted at the moment).

抽象クラスCMXFileWrapperは, XMLドキュメントをラップする各クラスの スーパークラスです. つまり, CrestMuseXMLに含まれるすべてのXMLドキュメントは, このクラスの サブクラスを介して扱われます. このクラスは, XMLドキュメントをDocument Object Model (DOM)として保持し, 別のXML Parserを用いてDOMを処理します. このDOMの処理は, このクラスで提供されるメソッドがカプセル化します.

本APIでは,処理のシンプルさを保つため, 同一のCMXFileWrapperオブジェクトに対して, 要素の追加と要素からの情報の取り出しを同時に行うことは認めていません. readfileメソッドを用いてファイルから読み込まれたCMXFileWrapperオブジェクトは immutableとなり, 要素を追加することはできません. また, 要素を追加するために生成した空オブジェクトは, finalize処理(finalizeDocumentメソッドを用いる)を行うまで, 後述のNodeInterfaceを取得することはできません. finalize処理後は, 要素の追加はできなくなります. (ただし, 現在は開発中のため, 便宜的にこのimmutablityは不完全なものに なっています.)

XMLドキュメントをファイルから読み込むにはreadfileメソッドを用います. readfileメソッドはstaticなメソッドで, ファイルを読み込んで それをラップするCMXFileWrapperオブジェクトを生成して返します. 返されるオブジェクトは正確にはCMXFileWrapperのサブクラスのオブジェクトで, たとえばMusicXMLドキュメントを読み込んだなら, MusicXMLWrapperオブジェクトが 返されます. よって, たとえばMusicXMLドキュメントをファイルから読み込む部分の記述は 以下のようになります.

  MusicXMLWrapper musicxml 
    = (MusicXMLWrapper)CMXFileWrapper.readfile(filename);
読み込んだファイルからCMXFileWrapperのどのサブクラスのインスタンスを生成するかは, 読み込んだドキュメントのトップレベルタグを見て判断します. トップレベルタグと対応するクラスの組が内部のハッシュマップに格納されており, これを用いて処理がなされます. CMX APIに最初から提供されているクラスはすでに 登録されていますが, ユーザが独自にXML形式と対応するクラスを作った場合, addClassTableメソッドを用いて追加することが可能です.

ファイルを読み込んでCMXFileWrapperオブジェクトを取得した後は, NodeInterfaceクラスを継承した各種クラスを通して情報を取得します. これは, (通常は)XMLドキュメントのある1つの要素をラップし, そこから情報を取り出す メソッドを提供します. 通常は, CMXFileWrapperの各サブクラスにおける内部クラスとして定義されます. たとえば, MusicXMLWrapperには, Part, Measure, Noteなどの内部クラスがあり, それぞれ, part, measure, note要素からの情報の取り出しをサポートします. 詳細は各サブクラスの説明をご覧ください.

空ドキュメントを生成するには, createDocumentメソッドを使って, たとえば次のようにします.

  SCCXMLWrapper sccxml
    = (SCCXMLWrapper)CMXFileWrapper.createDocument("scc");
ここでもreadfileメソッドと同様に, トップレベルタグを用いて生成すべきクラスを 判断しています. ここの例では, トップレベルタグ名を直接書いていますが, スペルミスを防ぐため, SCCXMLWrapper.TOP_TAGのような書き方が奨励されます.

要素の追加は, 現在のところ, シーケンシャルに要素を追加する手段が 提供されています. ファイルラッパのインスタンスを生成した時点では, トップレベルタグが「現在の要素」となっており, 「現在の要素」に対して 子要素やテキストなどを追加するメソッド(addChild, addText, etc.)を 利用して要素を増やしていきます. 子要素を追加すると, 「現在の要素」が追加された要素に移り, さらなる子要素を追加できます. returnToParentメソッドで「現在の要素」をその親要素に戻すことができます. その他にも, addChildAndText, addSibling, setAttributeメソッドを 利用できます. たとえば,

  <note>
    <pitch>
      <step>C</step>
      <octage>4</octave>
    </pitch>
    <duration>4</duration>
  </note>
を追加するには,
  xml.addChild("note");
  xml.addChild("pitch");
  xml.addChildAndText("step", "C");
  xml.addChildAndText("octave", "4");
  xml.returnToChild();
  xml.addChildAndText("duration", "4");
  xml.returnToChild();
とします. データの種類によっては, このようなシーケンシャルな方法が取れない場合が あると思われますので, その際には追加すべきデータを一時的に格納する クラスを用意しています. たとえばDeviationDataSetなどが該当します.

JAXPに対応したXMLパーサ(Xercesが望ましい)とXSLTプロセッサ (いまのところXalanのみ対応)が必要です.

バージョン:
0.21
作成者:
Tetsuro Kitahara (t.kitahara@ksc.kwansei.ac.jp)

フィールドの概要
static NodeLinkManager linkmanager
           
 
コンストラクタの概要
CMXFileWrapper()
           
 
メソッドの概要
 void addChild(org.w3c.dom.Node child)
          Adds the specified node to the current node.
 void addChild(java.lang.String tagname)
          Adds a child element with the specified tag name to the current node.
 void addChildAndText(java.lang.String tagname, double text)
          Adds a child element with the specified tag name and with the specified real number as its child to the current node.
 void addChildAndText(java.lang.String tagname, int text)
          Adds a child element with the specified tag name and with the specified integer as its child to the current node.
 void addChildAndText(java.lang.String tagname, java.lang.String text)
          Adds a child element with the specified tag name and with the specified text as its child to the current node.
static void addClassTable(java.lang.String toptagname, java.lang.String classname)
           
static void addDocumentTypeTable(java.lang.String toptagname, java.lang.String publicId, java.lang.String systemId)
           
protected  void addLinks(java.lang.String xpath, CMXFileWrapper target)
           
protected  void addLinks(java.lang.String xpath, org.w3c.dom.Document target)
           
 void addSibling(org.w3c.dom.Node sibling)
          Adds a sibling node of the current node.
 void addSibling(java.lang.String tagname)
          Adds a sibling node of the current node.
 void addText(double text)
          Adds a text node with the specified real number integer to the current node.
 void addText(int text)
          Adds a text node with the specified integer to the current node.
 void addText(java.lang.String text)
          Adds a text node with the specified text to the current node.
protected  void analyze()
          This method defines the initial processing required for extracting information from the XML document.
protected  void checkFinalized()
          Throws an exception if the document wrapped by this object is not finalized.
static CMXFileWrapper createDocument(java.lang.String toptagname)
          Creates an empty document with the specified top-tag name.
 void finalizeDocument()
          Forbids further element addition and prepares for getting information さらなる要素の追加をできなくし, 情報の取り出しのための準備をします.
protected  org.w3c.dom.Document getDocument()
          Returns the document wrapped by this object as an org.w3c.dom.Document object.
 java.lang.String getFileName()
          Returns the current file name.
protected  boolean isFinalized()
           
static CMXFileWrapper readfile(java.lang.String filename)
          Reads the specified file.
static CMXFileWrapper readfile(java.lang.String filename, CMXInitializer init)
          Reads the specified file.
 void returnToParent()
          Sets a new current node to the parent node of the current node.
protected  org.w3c.dom.NodeList selectNodeList(org.w3c.dom.Node node, java.lang.String xpath)
          Selects nodes based on the specified XPath expression with the specified context node and returns them as an org.w3c.dom.NodeList object.
protected  org.w3c.dom.NodeList selectNodeList(java.lang.String xpath)
          Selects nodes based on the specified XPath expression and returns them as an org.w3c.dom.NodeList object.
protected  org.w3c.dom.Node selectSingleNode(org.w3c.dom.Node node, java.lang.String xpath)
          Selects a single node based on the specified XPath expression with the specified context node.
protected  org.w3c.dom.Node selectSingleNode(java.lang.String xpath)
          Selects a single node based on the specified XPath expression.
 void setAttribute(java.lang.String name, double value)
          Adds an attribute to the current node.
 void setAttribute(java.lang.String name, int value)
          Adds an attribute to the current node.
 void setAttribute(java.lang.String name, java.lang.String value)
          Adds an attribute to the current node.
 void setAttributeNS(java.lang.String ns, java.lang.String name, double value)
          Adds an attribute to the current node with the specified name space.
 void setAttributeNS(java.lang.String ns, java.lang.String name, int value)
          Adds an attribute to the current node with the specified name space.
 void setAttributeNS(java.lang.String ns, java.lang.String name, java.lang.String value)
          Adds an attribute to the current node with the specified name space.
 void write(java.io.OutputStream out)
          Writes the document wrapped by this object to the specified stream.
 void write(java.io.Writer writer)
          Writes the document wrapped by this CMXFileWrapper object to the specified writer.
 void writefile(java.lang.String filename)
          Writes the document wrapped by this object to the specified file.
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

フィールドの詳細

linkmanager

public static final NodeLinkManager linkmanager
コンストラクタの詳細

CMXFileWrapper

public CMXFileWrapper()
メソッドの詳細

addClassTable

public static void addClassTable(java.lang.String toptagname,
                                 java.lang.String classname)
                          throws java.lang.ClassNotFoundException
例外:
java.lang.ClassNotFoundException

addDocumentTypeTable

public static void addDocumentTypeTable(java.lang.String toptagname,
                                        java.lang.String publicId,
                                        java.lang.String systemId)

getDocument

protected final org.w3c.dom.Document getDocument()

Returns the document wrapped by this object as an org.w3c.dom.Document object.

このオブジェクトが保持しているドキュメントを org.w3c.dom.Documentオブジェクトとして返します.


createDocument

public static CMXFileWrapper createDocument(java.lang.String toptagname)
                                     throws InvalidFileTypeException,
                                            javax.xml.parsers.ParserConfigurationException,
                                            org.xml.sax.SAXException

Creates an empty document with the specified top-tag name.

指定された名前のトップタグを持つ空のドキュメントを生成します.

例外:
InvalidFileTypeException - ...
javax.xml.parsers.ParserConfigurationException - ...
org.xml.sax.SAXException - ...

finalizeDocument

public final void finalizeDocument()
                            throws javax.xml.parsers.ParserConfigurationException,
                                   org.xml.sax.SAXException,
                                   javax.xml.transform.TransformerException,
                                   java.io.IOException

Forbids further element addition and prepares for getting information

さらなる要素の追加をできなくし, 情報の取り出しのための準備をします.

例外:
javax.xml.parsers.ParserConfigurationException
org.xml.sax.SAXException
javax.xml.transform.TransformerException
java.io.IOException

readfile

public static CMXFileWrapper readfile(java.lang.String filename)
                               throws java.io.IOException,
                                      javax.xml.parsers.ParserConfigurationException,
                                      org.xml.sax.SAXException,
                                      javax.xml.transform.TransformerException

Reads the specified file. After that, the analyze method is automatically called.

指定された名前のファイルを読み込みます. その後はanalyzeメソッドが 自動的に呼ばれます.

例外:
java.io.IOException - ...
javax.xml.parsers.ParserConfigurationException - ...
org.xml.sax.SAXException - ...
javax.xml.transform.TransformerException

readfile

public static CMXFileWrapper readfile(java.lang.String filename,
                                      CMXInitializer init)
                               throws java.io.IOException,
                                      javax.xml.parsers.ParserConfigurationException,
                                      org.xml.sax.SAXException,
                                      javax.xml.transform.TransformerException

Reads the specified file.

指定された名前のファイルを読み込みます. readfile(String)と同様にファイル読み込み後に, analyzeメソッドが呼ばれますが, その直前に指定されたイニシャライザが実行されます.

例外:
java.io.IOException - ...
javax.xml.parsers.ParserConfigurationException - ...
org.xml.sax.SAXException - ...
javax.xml.transform.TransformerException

getFileName

public final java.lang.String getFileName()

Returns the current file name.

現在のファイル名を返します,


write

public final void write(java.io.OutputStream out)
                 throws java.io.IOException,
                        org.xml.sax.SAXException

Writes the document wrapped by this object to the specified stream.

このオブジェクトが保持するドキュメントを 指定されたストリームに書き込みます.

例外:
java.io.IOException - ...
org.xml.sax.SAXException - ...

write

public final void write(java.io.Writer writer)
                 throws java.io.IOException,
                        org.xml.sax.SAXException

Writes the document wrapped by this CMXFileWrapper object to the specified writer.

このオブジェクトが保持するドキュメントを指定されたライタに書き込みます.

例外:
java.io.IOException - ...
org.xml.sax.SAXException - ...

writefile

public final void writefile(java.lang.String filename)
                     throws java.io.IOException,
                            org.xml.sax.SAXException

Writes the document wrapped by this object to the specified file.

このCMXFileWrapperオブジェクトが保持するドキュメントを 指定された名前のファイルに書き込みます.

例外:
java.io.IOException - ...
org.xml.sax.SAXException - ...

selectNodeList

protected final org.w3c.dom.NodeList selectNodeList(java.lang.String xpath)

Selects nodes based on the specified XPath expression and returns them as an org.w3c.dom.NodeList object.

指定されたXPath表現に基づいてノードをセレクトし, org.w3c.dom.NodeListオブジェクトとして返します.


selectNodeList

protected final org.w3c.dom.NodeList selectNodeList(org.w3c.dom.Node node,
                                                    java.lang.String xpath)

Selects nodes based on the specified XPath expression with the specified context node and returns them as an org.w3c.dom.NodeList object.

指定されたノードをコンテキストノードとして 指定されたXPath表現に基づいてノードをセレクトし, org.w3c.dom.NodeListオブジェクトとして返します.


selectSingleNode

protected final org.w3c.dom.Node selectSingleNode(java.lang.String xpath)

Selects a single node based on the specified XPath expression. The first node that matches the XPath is returned.

指定されたXPath表現に基づいてノードを1つセレクトします. マッチした最初のノードが返されます.


selectSingleNode

protected final org.w3c.dom.Node selectSingleNode(org.w3c.dom.Node node,
                                                  java.lang.String xpath)

Selects a single node based on the specified XPath expression with the specified context node. The first node that matches the XPath is returned.

指定されたノードをコンテキストノードとして 指定されたXPath表現に基づいてノードを1つセレクトします. マッチした最初のノードが返されます.


addLinks

protected final void addLinks(java.lang.String xpath,
                              CMXFileWrapper target)
                       throws javax.xml.transform.TransformerException
例外:
javax.xml.transform.TransformerException

addLinks

protected final void addLinks(java.lang.String xpath,
                              org.w3c.dom.Document target)
                       throws javax.xml.transform.TransformerException
例外:
javax.xml.transform.TransformerException

addChild

public final void addChild(java.lang.String tagname)

Adds a child element with the specified tag name to the current node. After that, the current node is changed to the added element.

現在のノードに指定されたタグ名のエレメントを追加します. 追加後は, 追加されたエレメントが現在のノードに設定されます.


addChild

public final void addChild(org.w3c.dom.Node child)

Adds the specified node to the current node. After that, the current node is changed to the added node.

現在のノードに指定されたノードを追加します. 追加後は, 追加されたノードが現在のノードに設定されます.


addText

public final void addText(java.lang.String text)

Adds a text node with the specified text to the current node.

現在のノードに指定されたテキストを持つテキストノードを追加します.


addText

public final void addText(int text)

Adds a text node with the specified integer to the current node.

現在のノードに指定された整数値を持つテキストノードを追加します.


addText

public final void addText(double text)

Adds a text node with the specified real number integer to the current node.

現在のノードに指定された実数値を持つテキストノードを追加します.


addChildAndText

public final void addChildAndText(java.lang.String tagname,
                                  java.lang.String text)

Adds a child element with the specified tag name and with the specified text as its child to the current node. This is equivalent to "addChild(tagname); addText(text); returnToParent();"

現在のノードに, 指定されたテキストを子に持つ指定されたタグ名のエレメントを 追加します. これは, "addChild(tagname); addText(text); returnToParent()"に等価です.


addChildAndText

public final void addChildAndText(java.lang.String tagname,
                                  int text)

Adds a child element with the specified tag name and with the specified integer as its child to the current node. This is equivalent to "addChild(tagname); addText(text); returnToParent();"

現在のノードに, 指定された整数値を子に持つ指定されたタグ名のエレメントを 追加します. これは, "addChild(tagname); addText(text); returnToParent()"に等価です.


addChildAndText

public final void addChildAndText(java.lang.String tagname,
                                  double text)

Adds a child element with the specified tag name and with the specified real number as its child to the current node. This is equivalent to "addChild(tagname); addText(text); returnToParent();"

現在のノードに, 指定された実数値を子に持つ指定されたタグ名のエレメントを 追加します. これは, "addChild(tagname); addText(text); returnToParent()"に等価です.


setAttribute

public final void setAttribute(java.lang.String name,
                               java.lang.String value)

Adds an attribute to the current node. The current node should be an element node.

現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


setAttribute

public final void setAttribute(java.lang.String name,
                               int value)

Adds an attribute to the current node. The current node should be an element node.

現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


setAttribute

public final void setAttribute(java.lang.String name,
                               double value)

Adds an attribute to the current node. The current node should be an element node.

現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


setAttributeNS

public final void setAttributeNS(java.lang.String ns,
                                 java.lang.String name,
                                 java.lang.String value)

Adds an attribute to the current node with the specified name space. The current node should be an element node.

指定された名前空間で, 現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


setAttributeNS

public final void setAttributeNS(java.lang.String ns,
                                 java.lang.String name,
                                 int value)

Adds an attribute to the current node with the specified name space. The current node should be an element node.

指定された名前空間で, 現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


setAttributeNS

public final void setAttributeNS(java.lang.String ns,
                                 java.lang.String name,
                                 double value)

Adds an attribute to the current node with the specified name space. The current node should be an element node.

指定された名前空間で, 現在のノードに属性を追加します. 現在のノードはエレメントでなければなりません.


addSibling

public final void addSibling(java.lang.String tagname)

Adds a sibling node of the current node.

現在のノードの弟ノードを追加します.


addSibling

public final void addSibling(org.w3c.dom.Node sibling)

Adds a sibling node of the current node.

現在のノードの弟ノードを追加します.


returnToParent

public final void returnToParent()

Sets a new current node to the parent node of the current node.

現在のノードの親ノードを新たな現在のノードに設定します.


isFinalized

protected final boolean isFinalized()

checkFinalized

protected void checkFinalized()

Throws an exception if the document wrapped by this object is not finalized.

このオブジェクトがラップするドキュメントがfinalizedされていなかったら, 例外をスローします.


analyze

protected void analyze()
                throws javax.xml.transform.TransformerException,
                       java.io.IOException,
                       javax.xml.parsers.ParserConfigurationException,
                       org.xml.sax.SAXException

This method defines the initial processing required for extracting information from the XML document. This is called by the runAll() method in the CMXCommand class after readfile() method before run() method. The default implementation does not do anything.

このメソッドでは, XMLドキュメントから情報を取り出す上で必要な初期の処理を 記述します. これは, CMXCommandクラスのrunAll()メソッドから, readfile()メソッドの後, run()メソッドの前に呼び出されます. デフォルトの実装では何もしません.

例外:
javax.xml.transform.TransformerException
java.io.IOException
javax.xml.parsers.ParserConfigurationException
org.xml.sax.SAXException