MusicXML Tasks: Conversion Code

Conversion Code

MusicXML to Java Beans

Handlers

When converting from MusicXML to Java beans, a series of handler classes are called. The handlers iterate the XML document, calling a series of nested handlers reflecting the hierarchical nature of the document, and creating the Java beans structure along the way.

The Score is first created by the ScoreHandler:

package com.musicxmltasks.musicxml.handler;

import com.musicxmltasks.musicxml.score.PartListItem;
import com.musicxmltasks.musicxml.score.Score;
import com.musicxmltasks.musicxml.score.ScorePart;
import com.musicxmltasks.util.StringUtil;
import com.musicxmltasks.xml.XmlUtil;
import org.w3c.dom.Element;

import java.util.List;

public class ScoreHandler {
    private Score score;

    public ScoreHandler() {

    }

    public Score getScore() {
        return score;
    }

    public void handle(Element element) {
        score = new Score();

        // handle the score header
        ScoreHeaderHandler scoreHeaderHandler = new ScoreHeaderHandler(score.getScoreHeader());
        scoreHeaderHandler.handle(element);

        // handle the parts
        List<Element> partElements = XmlUtil.getChildElements(element, "part");
        for(PartListItem partListItem : score.getScoreHeader().getPartListItems()) {
            if(partListItem instanceof ScorePart) {
                ScorePart scorePart = (ScorePart) partListItem;
                String partId = scorePart.getScorePartId();
                for (Element partElement : partElements) {
                    if (partId.equals(partElement.getAttribute("id"))) {
                        PartHandler partHandler = new PartHandler(score.getParts());
                        partHandler.handle(partElement);
                    }
                }
            }
        }

        String scoreVersion = element.getAttribute("version");
        if (StringUtil.isNotEmpty(scoreVersion)) score.setVersion(scoreVersion);
    }
}

From within ScoreHandler, a series of PartHandler classes create the part and its measures:

package com.musicxmltasks.musicxml.handler;

import com.musicxmltasks.musicxml.score.Measure;
import com.musicxmltasks.musicxml.score.Part;
import com.musicxmltasks.xml.XmlUtil;
import org.w3c.dom.Element;

import java.util.List;

import static com.musicxmltasks.musicxml.util.MusicXmlUtil.DEBUG;

public class PartHandler implements ScoreElementHandler {
    private List<Part> parts;

    public PartHandler(List<Part> parts) {
        this.parts = parts;
    }

    public void handle(Element element) {
        Part part = new Part();

        part.setPartId(element.getAttribute("id"));
        if (DEBUG) System.err.println("Part " + part.getPartId());

        List<Measure> measures = part.getMeasures();
        List<Element> measureElements = XmlUtil.getChildElements(element, "measure");
        for(Element measureElement : measureElements) {
            MeasureHandler measureHandler = new MeasureHandler(measures);
            measureHandler.handle(measureElement);
        }

        parts.add(part);
    }
}

Then a series of MusicDataHandler classes are called from within MeasureHandler:

package com.musicxmltasks.musicxml.handler;

import com.musicxmltasks.musicxml.factory.DirectionFactory;
import com.musicxmltasks.musicxml.factory.LinkFactory;
import com.musicxmltasks.musicxml.factory.NoteFactory;
import com.musicxmltasks.musicxml.util.TypeUtil;
import com.musicxmltasks.musicxml.score.Measure;
import com.musicxmltasks.musicxml.score.MusicData;
import com.musicxmltasks.util.MathUtil;
import com.musicxmltasks.xml.XmlUtil;
import org.w3c.dom.Element;

import java.util.List;

import static com.musicxmltasks.musicxml.util.MusicXmlUtil.DEBUG;

public class MeasureHandler implements ScoreElementHandler {
    private List<Measure> measures;

    public MeasureHandler(List<Measure> measures) {
        this.measures = measures;
    }

    public void handle(Element element) {
        String measureNumber = element.getAttribute("number");
        if (DEBUG) System.err.println("Measure " + measureNumber);
        Measure measure = new Measure();
        measure.setElementId(element.getAttribute("id"));
        measure.setNumber(measureNumber);
        measure.setText(element.getAttribute("text"));
        measure.setImplicit(TypeUtil.getYesNo(element.getAttribute("implicit")));
        measure.setNonControlling(TypeUtil.getYesNo(element.getAttribute("non-controlling")));
        measure.setWidth(MathUtil.newBigDecimal(element.getAttribute("width")));

        List<MusicData> musicDataList = measure.getMusicDataList();
        List<Element> measureSubelements = XmlUtil.getChildElements(element);

        for (Element measureSubelement : measureSubelements) {
            MusicDataHandler handler = null;
            MusicData musicData = null;
            String elementName = measureSubelement.getTagName();
            switch (elementName) {
                case "note":
                    handler = new NoteHandler();
                    break;
                case "backup":
                    handler = new BackupHandler();
                    break;
                case "forward":
                    handler = new ForwardHandler();
                    break;
                case "direction":
                    handler = new DirectionHandler();
                    break;
                case "attributes":
                    handler = new AttributesHandler();
                    break;
                case "harmony":
                    handler = new HarmonyHandler();
                    break;
                case "figured-bass":
                    musicData = NoteFactory.newFiguredBass(measureSubelement);
                    break;
                case "print":
                    handler = new PrintHandler();
                    break;
                case "sound":
                    musicData = DirectionFactory.newSound(measureSubelement);
                    break;
                case "barline":
                    handler = new BarlineHandler();
                    break;
                case "grouping":
                    handler = new GroupingHandler();
                    break;
                case "link":
                    musicData = LinkFactory.newLink(measureSubelement);
                    break;
                case "bookmark":
                    musicData = LinkFactory.newBookmark(measureSubelement);
                    break;
            }

            if (handler != null) musicData = handler.handle(measureSubelement);
            if(musicData != null) {
                musicDataList.add(musicData);
                musicData.setMeasure(measure);
            }
        }

        measures.add(measure);
    }
}

and so on, until the entire score document is iterated.

When completed, the populated and annotated beans can then used to save to the database or to build LilyPond output.

Factories

Repetitive calls to create beans are handled by bean factories.

For example, a Display bean can occur in many places throughout the structure, so these calls are handled by the DisplayFactory:

public class DisplayFactory {
    private DisplayFactory() {

    }

    public static Display newDisplay(Element element) {
        if (element == null) return null;

        BigDecimal defaultX = MathUtil.newBigDecimal(element.getAttribute("default-x"));
        BigDecimal defaultY = MathUtil.newBigDecimal(element.getAttribute("default-y"));
        BigDecimal relativeX = MathUtil.newBigDecimal(element.getAttribute("relative-x"));
        BigDecimal relativeY = MathUtil.newBigDecimal(element.getAttribute("relative-y"));

        if (invalidPositionValue(defaultX, "default-x")) defaultX = null;
        if (invalidPositionValue(defaultY, "default-y")) defaultY = null;
        if (invalidPositionValue(relativeX, "relative-x")) relativeX = null;
        if (invalidPositionValue(relativeY, "relative-y")) relativeY = null;

        Placement placement = FactoryUtil.enumValue(Placement.class, element.getAttribute("placement"));
        Font font = newFont(element);
        String color = element.getAttribute("color");
        Halign halign = FactoryUtil.enumValue(Halign.class, element.getAttribute("halign"));
        Valign valign = FactoryUtil.enumValue(Valign.class, element.getAttribute("valign"));

        if (defaultX == null && defaultY == null && relativeX == null && relativeY == null && placement == null && font == null && StringUtil.isEmpty(color) && halign == null && valign == null) return null;

        Display display = new Display();
        display.setDefaultX(defaultX);
        display.setDefaultY(defaultY);
        display.setRelativeX(relativeX);
        display.setRelativeY(relativeY);
        display.setPlacement(placement);
        display.setFont(font);
        display.setColor(color);
        display.setHalign(halign);
        display.setValign(valign);

        return display;
    }

Java Beans to MusicXml and LilyPond Output

Java beans are converted to MusicXml or LilyPond text output by iterating the beans hierarchical structure.

MusicXML Builder Output

Iteration begins with a ScoreBuilder and continues through the score parts:

public class ScoreBuilder extends MusicDataBuilder {
    private Score score;

    public ScoreBuilder(Score score) {
        this.score = score;
    }

    public StringBuilder build() {
        buildDocumentDeclaration();

        buildOpenElement("score-partwise");
        buildAttribute("version", score.getVersion());
        buildCloseElement();

        ScoreHeaderBuilder scoreHeaderBuilder = new ScoreHeaderBuilder(score.getScoreHeader());
        append(scoreHeaderBuilder.build().toString());

        for (Part part : score.getParts()) {
            PartBuilder partBuilder = new PartBuilder(part);
            append(partBuilder.build().toString());
        }

        buildEndElement("score-partwise");

        return stringBuilder;
    }

LilyPond Builder Output

Likewise, LilyPond iteration begins with a ScoreBuilder and continues through the score parts:

public class ScoreBuilder extends LilypondBuilder {
    private Score score;
    private Map<String, Integer> primaryVoiceStaves = new HashMap<>();

    public ScoreBuilder(Score score) {
        this.score = score;
    }

    public Score getScore() {
        return score;
    }

    public StringBuilder build() throws BuildException {
        // score header
        ScoreHeaderBuilder scoreHeaderBuilder = new ScoreHeaderBuilder(score.getScoreHeader());
        append(scoreHeaderBuilder.build().toString());

        // begin score
        appendStartSection("\\score {");
        appendStartSection("<<");

        List<PartListItem> partListItems = score.getScoreHeader().getPartListItems();
        if(partListItems.isEmpty()) {
            throw new BuildException("Score header part list not found");
        }

        boolean scorePartFirst = partListItems.get(0) instanceof ScorePart;

        if(scorePartFirst) {
            appendStartSection("<<");
        }

        for (PartListItem partListItem : partListItems) {
            if(partListItem instanceof PartGroup) {
                PartGroup partGroup = (PartGroup)partListItem;
                Connection partGroupType = partGroup.getType();
                if (partGroupType == Connection.START) {
                    appendStartSection("\\new StaffGroup <<");
                } else if (partGroupType == Connection.STOP) {
                    appendEndSection(">>");
                }
            } else if(partListItem instanceof ScorePart) {
                ScorePart scorePart = (ScorePart)partListItem;
                appendStartSection("<<");
                buildPart(scorePart);
                appendEndSection(">>");
            }
        }

        if(scorePartFirst) {
            appendEndSection(">>");
        }

        // end score
        appendEndSection(">>");
        appendEndSection("}");

        return stringBuilder;
    }

The LilyPond conversion code, however, only implements a fraction of MusicXML document conversion to LilyPond features, due to the richness of the MusicXML and LilyPond definitions. The user is expected to adjust the output once the conversion is complete if features are noted as unimplemented, or if the conversion produces any anomalies.

LilyPond conversion fails at the measure level, so if, for example, a measure's duration count doesn't add up, the conversion will output a measure-length spacer for that measure, and output the exception to the console.

Because there are so many possible output features and only some of them are implemented, the Java code at the music-data level uses reflection to construct the expected builder class method call. If the method is unimplemented, a message is sent to console output indicating the unimplemented method.

package com.musicxmltasks.lilypond.musicdata;

import com.musicxmltasks.lilypond.LilypondBuilder;
import com.musicxmltasks.lilypond.MeasureBuilder;
import com.musicxmltasks.lilypond.exception.BuildException;
import com.musicxmltasks.lilypond.part.PartBuilder;
import com.musicxmltasks.util.MathUtil;

import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import static com.musicxmltasks.musicxml.util.MusicXmlUtil.DEBUG;

public class MusicDataBuilder extends LilypondBuilder {
    private Object musicData;
    private BigDecimal unhandledDuration = MathUtil.ZERO;

    public MusicDataBuilder(Object musicData) {
        this.musicData = musicData;
    }

    public MusicDataBuilder() {

    }

    public Object getMusicData() {
        return musicData;
    }

    public BigDecimal getUnhandledDuration() {
        return unhandledDuration;
    }

    public void setUnhandledDuration(BigDecimal unhandledDuration) {
        this.unhandledDuration = unhandledDuration;
    }

    public StringBuilder build() throws BuildException {
        if (musicData == null) return stringBuilder;

        String musicDataClassName = musicData.getClass().getName();
        musicDataClassName = musicDataClassName.replace("com.musicxmltasks.musicxml.", "");

        List<String> classNameParts = new ArrayList<>(Arrays.asList(musicDataClassName.split("\\.")));

        String objectClassName = classNameParts.remove(classNameParts.size() - 1);
        String builderRootClassName = classNameParts.remove(classNameParts.size() - 1);
        builderRootClassName = builderRootClassName.substring(0, 1).toUpperCase() + builderRootClassName.substring(1);
        String builderPackageName = "com.musicxmltasks.lilypond.musicdata.";

        String builderObjectName = builderRootClassName + "Builder";
        String builderClassName = builderPackageName + builderObjectName;
        String builderMethodName = "build" + objectClassName;

        try {
            Class builderClass = Class.forName(builderClassName);
            Method builderMethod = builderClass.getMethod(builderMethodName, musicData.getClass());
            append(builderMethod.invoke(builderClass.getDeclaredConstructor().newInstance(), musicData).toString());
        } catch (InvocationTargetException e) {
            if (e.getCause() instanceof BuildException) {
                // Note exception but continue anyway
                System.err.println(PartBuilder.CURRENT_PART_ID + ", Measure " + MeasureBuilder.CURRENT_MEASURE_NUMBER + ": " + e.getCause().getMessage());
                setUnhandledDuration(((BuildException)e.getCause()).getUnhandledDuration());
            } else {
                displayException(e);
                if(DEBUG) e.printStackTrace();
            }
        } catch (NoSuchMethodException e) {
            System.err.println("Unimplemented method: " + builderObjectName + "." + builderMethodName + "(" + objectClassName + ")");
        } catch (Exception e) {
            displayException(e);
            if(DEBUG) e.printStackTrace();
        }

        return stringBuilder;
    }
}

LilyPond output implementations can then be added individually as desired, in the form of buildXXX methods that correspond to bean class names.

For example, the DirectiontypeBuilder implements only those methods that have direction type output implemented for LilyPond:

public class DirectiontypeBuilder extends MusicDataBuilder {
    public DirectiontypeBuilder() {

    }

    public StringBuilder buildRehearsal(Rehearsal rehearsal) {
        append("\\mark ");
        formattedDisplayBuild(rehearsal.getDisplay(), rehearsal.getTextFormat());

        return stringBuilder;
    }

    public StringBuilder buildSegno(Segno segno) {
        append("\\segno");

        return stringBuilder;
    }

    public StringBuilder buildWords(Words words) {
        if (words.isTextMark()) append("\\mark ");
        formattedDisplayBuild(words.getDisplay(), words.getTextFormat());

        return stringBuilder;
    }

    public StringBuilder buildCoda(Coda coda) {
        appendLine("\\coda");

        return stringBuilder;
    }

    public StringBuilder buildWedge(Wedge wedge) {
        WedgeType wedgeType = wedge.getType();
        switch (wedgeType) {
            case CRESCENDO:
                append("\\<");
                break;
            case DIMINUENDO:
                append("\\>");
                break;
            case STOP:
                append("\\!");
                break;
            case INVALID:
                System.err.println("Wedge not handled");
                break;
        }
    }
    [additional methods ...]