EXPLANATION OF THIS SECTION

This section provides hints on how programmers can extend jSymbolic's functionality. A particular emphasis is placed on designing and adding new features.

FIRST STEPS

The first thing to do is to download the development version of jSymbolic from jmir.sourceforge.net. It is important to use this distribution rather than the user distribution, as only the former includes source code and associated Javadocs.

The user can use a variety of IDEs or text editors to modify the source code. NetBeans was used to publish jSymbolic, but this is simply a matter of preference.

It may be necessary to link within the chosen IDE to the libraries used by jSymbolic; although these are indeed provided as pre-compiled jar files, the source code for each of them is also provided in the development distribution of jSymbolic:

• ACE: A metalearning tool. jSymbolic uses it to save ACE XML files. Like jSymbolic, ACE is part of the jMIR framework.
• UtilityClasses: A set of utility classes providing a variety of general-purpose functionality. jSymbolic uses it to perform miscellaneous tasks, especially those relating to parsing audio files. Like jSymbolic, these are part of the jMIR framework.
• jMei2Midi: Conversion software that converts MEI data to MIDI data. This includes an MEI pipeline which can extract and preserve MEI-specific features that would be lost in the conversion to MIDI. The software can be found at the jMei2Midi page as a Maven project.

One additional miscellaneous note of interest to take into account when configuring one's IDE to compile jSymbolic: the main class that the jSymbolic.jar uses to begin extecution should be set to jsymbolic.jSymbolicRunner, not jsymbolic.Main. This is in order to allow the JRE heap size to be automatically set appropriately.

For more details on how jSymbolic is constructed, the reader may wish to consult jSymbolic's Javadocs and extensive source code documentation, of course. The manual's Processing Sequence and Class Structure sections also provide useful resources for getting an idea of how the software is constructed and operates as a whole.

ADDING NEW FEATURES

One of the most useful ways of extending jSybmolic is to implement new custom features. Fortunately, this is easy to do in jSymbolic, which is designed to be particularly modular and easily extensible in this sense.

The first step in creating a new feature is to create a new class in the jsymbolic.features package that extends the MIDIFeatureExtractor abstract class. This new class must implement the specified extractFeature abstract method, and it should also have a constructor with no arguments that sets the MIDIFeatureExtractor superclass' fields. If desired, dependencies on other features can also be set here, or they can be set to null. The extractFeature method will automatically be provided with raw MIDI data, the values of other features and useful preliminary data structures stored in an jsymbolic.processing.MIDIIntermediateRepresentations object when it is called by jSymbolic. Programmers may consult the many other feature implementations in the jsymbolic.features package for examples to follow. It should be noted, incidentally, that features extending MIDIFeatureExtractor are extracted from all input files, including MEI (which jSymbolic automatically converts to MIDI, among other things), not just files that start off as MIDI files.

A slightly modified procedure is to be followed if the feature to be implemented is an MEI-specific feature. In such a case, the MEIFeatureExtractor abstract class should be extended by the new feature rather than the MIDIFeatureExtractor abstract class. The NumberOfGraceNotesFeature class provides a good example of such a feature. In this case, a constructor must be written (as with MIDIFeatureExtractor features), and the abstract method that must be implemented is called extractMEIFeature. This method will be automatically provided provided with MEI-specific data when it is called by jSymbolic, as well as with raw MIDI data, the values of other features and useful preliminary data structures stored in an jsymbolic.processing.MIDIIntermediateRepresentations object. Note that the MEI-specific data comes from the jMei2Midi software, which may need to be updated as well to provide necessary data.

Once a new feature class is finished, be it a MIDIFeatureExtractor or a MEIFeatureExtractor, it must then be added to the jsymbolic.processing.FeatureExtractorAccess class in order to be automatically included in jSymbolic processing. This addition must occur in two places: 1) the new feature must be instantiated (without arguments) in the all_implemented_feature_extractors array, and 2) a properly ordered value of true or false must be added to the default_features_to_save boolean array in order to indicate whether this new features is to be extracted by default or not. FeatureExtractorAccess will automatically perform error checking (via its printWarningReportIfFeaturesAddedImproperly() method) upon instantiation in order to make sure that these two steps have been performed properly.

This is all that needs to be done to add a new feature to all aspects of jSymbolic's interface and processing. After recompillation, jSymbolic's GUI, command line interface and API will all now include the new feature. Even better, jSymbolic will automatically handle feature extraction scheduling to take feature dependencies into account.

One final thing that some users may wish to do: if an optional configuration settings file is being used that specifies features to extract, then the new feature should be added to the list of features to extract in this file (this can be done most easily by simply saving a configurationfile from the jSymbolic GUI).

CREATING NEW KINDS OF CONFIGURATION FILES

Programmers may potentially wish to create a modified version of jSymbolic's configuration settings file. In order to do so, one can begin by going to the jsymbolic.configuration package and extending the following two abstract classes:

• ConfigurationFileValidator: All abstract methods in this class must be implemented. This will allow for the parseConfigFile template method pattern to be used and appropriately parse the configuration file. This is done in the CommandLineSwitchEnum class and so the new subclass will simply need to be changed in order to parse the new configuration file format. This allows for very quick and easy extensibility if a new configuration file format is desired. Notice that the parseConfigFile method takes in a List of HeaderEnums, and the enums in the list will indeed be validated. Any other headers not in this list but found in the configuration file will result in an error message and termination of jSymbolic execution.


• ConfigurationFileWriter: All abstract methods in this class must be implemented. This will allow the write template method pattern to be used and thus write out the specified configuration file format. Notice that the write method takes in a List of HeaderEnums and the enums in the list will write out those sections of the configuration file. HeaderEnums not in the list will not be written out. This method is called in the FeatureSelectorPanel class when the Save GUI Configuration button is pressed in the GUI.

-top of page-