info.bioinfweb.jphyloio

## Interface ReadWriteParameterNames

- All Known Implementing Classes:
    ReadWriteParameterMap

      public interface ReadWriteParameterNames

  Provides the names of parameters supported by one or more readers or writers included in JPhyloIO. Such names are used as keys in instances of `ReadWriteParameterMap`. Different readers and writers support different sets of parameters. Which are supported is defined in the documentation of each reader and writer and can also be programmatically determined using `JPhyloIOFormatInfo.getSupportedParameters(boolean)`.

  All parameter names defined here start with the prefix "info.bioinfweb.jphyloio." as defined by `KEY_PREFIX`. Developers of third party readers or writers may define additional parameters, but must make sure that these are globally unique by using their own reverse domain name as an unique prefix.

  Since:
    0.1.0
  Author:
    Ben Stöver

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `KEY_ALLOW_DEFAULT_NAMESPACE` This parameter can be used to specify whether readers of XML formats shall also accept tags of their target format without any namespace definition.
    `static java.lang.String` | `KEY_ALLOW_INTERLEAVED_PARSING` Parameter which determines whether interleaved input files (currently only in Phylip) shall be supported by this parser instance.
    `static java.lang.String` | `KEY_ALWAYS_WRITE_NEXUS_NODE_LABELS` This parameter can be used to specify whether a nodes in a Nexus TREE command should always be written as full labels of if their index in the associated TAXA block should be used, when possible.
    `static java.lang.String` | `KEY_APPLICATION_NAME` Identifies the name of the application generating the output.
    `static java.lang.String` | `KEY_APPLICATION_URL` Identifies the URL of the application generating the output.
    `static java.lang.String` | `KEY_APPLICATION_VERSION` Identifies the version number of the application generating the output.
    `static java.lang.String` | `KEY_CREATE_UNKNOWN_COMMAND_EVENTS` This parameter can be used to specify whether special events shall be fired if the reader encounters unknown commands (e.g.
    `static java.lang.String` | `KEY_CUSTOM_XML_NAMESPACE_HANDLING` This parameter will be used by XML writers to determine whether namespaces used or declared in customXML shall be managed together with other namespaces of the document by the used JPhyloIO writer.
    `static java.lang.String` | `KEY_EXPECT_E_NEWICK` This parameter will only be used by `NexusEventReader` and `NewickEventReader` and allows to specify whether the eNewick extension of Newick strings is supported.
    `static java.lang.String` | `KEY_GENERATE_NEXUS_TRANSLATION_TABLE` This parameter can be used to specify whether a `TRANSLATE` command should be included in the `TREES` block of a Nexus document.
    `static java.lang.String` | `KEY_IGNORE_COMMENTS` This parameter is reserved for future use and currently not supported by any reader or writer in JPhyloIO.
    `static java.lang.String` | `KEY_LABEL_EDITING_REPORTER` Writers may have to edit names of OTUs, sequences or tree/network nodes according to the limitations of a specific format.
    `static java.lang.String` | `KEY_LINE_LENGTH` Specifies the preferred line length for writers that support this.
    `static java.lang.String` | `KEY_LINE_SEPARATOR` If a line separator different from that of the current operating system shall be used by a writer, it can be specified using this key.
    `static java.lang.String` | `KEY_LOGGER` Identifies an application logger to write log messages to.
    `static java.lang.String` | `KEY_MATCH_TOKEN` Parameter used with instances of `JPhyloIOEventReader` that specifies the match token in the sequences to be read.
    `static java.lang.String` | `KEY_MAXIMUM_COMMENT_LENGTH` Parameter used with instances of `JPhyloIOEventReader` that specifies the maximal length of the text in a `CommentEvent`.
    `static java.lang.String` | `KEY_MAXIMUM_NAME_LENGTH` This parameter can be used to specify a custom maximum lengths for element names.
    `static java.lang.String` | `KEY_MAXIMUM_TOKENS_TO_READ` Parameter used with instances of `JPhyloIOEventReader` that specifies the maximal number of tokens to be included in a single `SequenceTokensEvent`.
    `static java.lang.String` | `KEY_NEXML_TOKEN_DEFINITION_LABEL` This parameter will only be used by `NeXMLEventWriter` and allows to define whether the token name or the label of a `SingleTokenDefinitionEvent` shall be written to the label-attribute of a state element in a NeXML characters block of type `standard` or `protein`.
    `static java.lang.String` | `KEY_NEXML_TOKEN_DEFINITION_LABEL_METADATA` This parameter will only be used by `NeXMLEventWriter` and allows to define whether the token name and the label of a `SingleTokenDefinitionEvent` shall be represented as metadata always, never or only if one of these properties could not be written to the label-attribute of a state element in a NeXML characters block of type `standard` or `protein`.
    `static java.lang.String` | `KEY_NEXML_TOKEN_TRANSLATION_STRATEGY` This parameter will only be used by `NeXMLEventReader` and allows to define the way tokens stored in a NeXML characters block of type `standard` should be parsed.
    `static java.lang.String` | `KEY_NEXUS_BLOCK_HANDLER_MAP` This parameter will only be used by `NexusEventReader` and allows to define a custom block handler map.
    `static java.lang.String` | `KEY_NEXUS_COMMAND_READER_FACTORY` This parameter will only be used by `NexusEventReader` and allows to define a custom command reader factory.
    `static java.lang.String` | `KEY_OBJECT_TRANSLATOR_FACTORY` This parameter can be used to specify a custom instance of `ObjectTranslatorFactory` that is used by readers to create literal meta object values and writers to obtain string and XML representations of objects.
    `static java.lang.String` | `KEY_PHYLOXML_CONSIDER_PHYLOGENY_AS_TREE` This parameter will only be used by `PhyloXMLEventReader` and allows to define if trees read from a PhyloXML file should always be considered as trees or networks.
    `static java.lang.String` | `KEY_PHYLOXML_EVENT_ID_TRANSLATION_MAP` This parameter will only be used by `PhyloXMLEventReader` and allows to obtain an object that maps the IDs used in a PhyloXML document to refer to specific elements to according JPhyloIO event IDs.
    `static java.lang.String` | `KEY_PHYLOXML_METADATA_TREATMENT` This parameter will only be used by `PhyloXMLEventWriter` and allows to define which metadata events from an adapter should be written.
    `static java.lang.String` | `KEY_PREFIX` The prefix of all keys used in JPhyloIO for parameter maps.
    `static java.lang.String` | `KEY_RELAXED_PHYLIP` Parameter which determines whether Phylip readers should consider the input as relaxed Phylip (allowing longer taxon names).
    `static java.lang.String` | `KEY_REPLACE_MATCH_TOKENS` Parameter used with instances of `JPhyloIOEventReader` that specifies whether possibly encountered match tokens shall be replaced by the according tokens from the first sequence.
    `static java.lang.String` | `KEY_SEQUENCE_EXTENSION_TOKEN` This parameter can be used to specify that sequences with unequal lengths (in character matrix data) shall be filled up with, until all have an equal length.
    `static java.lang.String` | `KEY_TRANSLATE_INTERNAL_NODE_NAMES` This parameter will only be used by `NexusEventReader` and allows to define whether internal node names should be translated using the taxon list from a `TAXA` block or a translation table.
    `static java.lang.String` | `KEY_USE_OTU_LABEL` This parameter will be used by some `JPhyloIOEventReader`s to determine whether the label of an associated OTU should be used as a label, if none was present in an element.
    `static java.lang.String` | `KEY_WRITER_INSTANCE` This key is used by implementations of `JPhyloIOEventWriter` to provide a reference to the currently active instance.

- - ### Field Detail

    - #### KEY_PREFIX

          static final java.lang.String KEY_PREFIX

      The prefix of all keys used in JPhyloIO for parameter maps.

      Application or third party library developers who implement additional readers or writers using additional parameter keys should define keys according to the reverse domain name pattern that do not start with this prefix ("info.bioinfweb.jphyloio.").

      See Also:
        Constant Field Values

    - #### KEY_WRITER_INSTANCE

          static final java.lang.String KEY_WRITER_INSTANCE

      This key is used by implementations of `JPhyloIOEventWriter` to provide a reference to the currently active instance. The according entry is useful for implementations of a data adapter, if they wish to obtain information on the writer requesting data from them.

      Note that this key identifies a return value of a writer implementation and not a parameter for the writer. Entries provided by the implementation prior to calling a write method of a writer will be directly overwritten by the actual target format.

      The value must have the type `JPhyloIOEventWriter`.

      See Also:
        Constant Field Values

    - #### KEY_LOGGER

          static final java.lang.String KEY_LOGGER

      Identifies an application logger to write log messages to.

      The value should have the type `ApplicationLogger`.

      See Also:
        Constant Field Values

    - #### KEY_MAXIMUM_TOKENS_TO_READ

          static final java.lang.String KEY_MAXIMUM_TOKENS_TO_READ

      Parameter used with instances of `JPhyloIOEventReader` that specifies the maximal number of tokens to be included in a single `SequenceTokensEvent`. Some readers may ignore this parameter. (Refer to the documentations of the single readers for details on which parameters each of them supports.)

      The value should be an integer value (e.g. `Integer`).

      See Also:
        Constant Field Values

    - #### KEY_MAXIMUM_COMMENT_LENGTH

          static final java.lang.String KEY_MAXIMUM_COMMENT_LENGTH

      Parameter used with instances of `JPhyloIOEventReader` that specifies the maximal length of the text in a `CommentEvent`. Readers that support this parameter will separate longer comments into separate events. (Refer to the documentations of the single readers for details on which parameters each of them supports.)

      The value should be an integer value (e.g. `Integer`).

      See Also:
        Constant Field Values

    - #### KEY_REPLACE_MATCH_TOKENS

          static final java.lang.String KEY_REPLACE_MATCH_TOKENS

      Parameter used with instances of `JPhyloIOEventReader` that specifies whether possibly encountered match tokens shall be replaced by the according tokens from the first sequence. Some readers may ignore this parameter and always show a default behavior. (Refer to the documentations of the single readers for details on which parameters each of them supports.)

      The value should have the type `Boolean`. If `true` is specified, match tokens will be replaced, if `false` is specified match tokens will be treated as valid tokens and directly by passed to the sequence token events.

      See Also:
        `KEY_MATCH_TOKEN`, Constant Field Values

    - #### KEY_MATCH_TOKEN

          static final java.lang.String KEY_MATCH_TOKEN

      Parameter used with instances of `JPhyloIOEventReader` that specifies the match token in the sequences to be read. Note that this parameter is only relevant if no match token is directly defined in the format. (Refer to the documentations of the single readers for details on which parameters each of them supports.)

      The value should have the type `String`. If it is omitted, readers supporting this parameter will use `"."` as the default match token.

      See Also:
        `KEY_REPLACE_MATCH_TOKENS`, Constant Field Values

    - #### KEY_RELAXED_PHYLIP

          static final java.lang.String KEY_RELAXED_PHYLIP

      Parameter which determines whether Phylip readers should consider the input as relaxed Phylip (allowing longer taxon names).

      The value must have the type `Boolean`. If `true` is specified, relaxed Phylip will be expected. If `false` is specified or this parameter is omitted, strict Phylip will be expected.

      See Also:
        Constant Field Values

    - #### KEY_ALLOW_INTERLEAVED_PARSING

          static final java.lang.String KEY_ALLOW_INTERLEAVED_PARSING

      Parameter which determines whether interleaved input files (currently only in Phylip) shall be supported by this parser instance. (In order to support this feature some readers need to keep a list of all sequence names. To parse files with a very large number of sequences which are not interleaved, this feature can be switched off to save memory. If this switch is set to `true` non-interleaved files can also still be parsed.)

      Note that not all readers for possibly interleaved formats will make use of this parameter. (Refer to the single reader documentations for details.)

      The value must have the type `Boolean`. If `true` is specified or this parameter is omitted, parsing interleaved files will be possible. If `false` is specified parsing interleaved files will not be possible.

      See Also:
        Constant Field Values

    - #### KEY_EXPECT_E_NEWICK

          static final java.lang.String KEY_EXPECT_E_NEWICK

      This parameter will only be used by `NexusEventReader` and `NewickEventReader` and allows to specify whether the eNewick extension of Newick strings is supported. As a consequence, all trees will be considered as networks when reading Newick and Nexus files, when this option is activated.

      In Nexus this parameter only influences how Newick strings in `TREE` commands in `TREES` blocks are handled. Support for custom `NETWORKS` blocks containing eNewick strings can be added independently using `NexusEventReader.addENewickNetworksBlockSupport()`.

      It must have the type `Boolean`. If it is omitted eNewick will not be expected. Network nodes will appear twice and labels will still contain possible network information.

      See Also:
        `NexusEventReader.addENewickNetworksBlockSupport()`, Constant Field Values

    - #### KEY_NEXUS_BLOCK_HANDLER_MAP

          static final java.lang.String KEY_NEXUS_BLOCK_HANDLER_MAP

      This parameter will only be used by `NexusEventReader` and allows to define a custom block handler map.

      It must have the type `NexusBlockHandler`. If it is omitted a block handler for all blocks supported in JPhyloIO will be used.

      See Also:
        Constant Field Values

    - #### KEY_TRANSLATE_INTERNAL_NODE_NAMES

          static final java.lang.String KEY_TRANSLATE_INTERNAL_NODE_NAMES

      This parameter will only be used by `NexusEventReader` and allows to define whether internal node names should be translated using the taxon list from a `TAXA` block or a translation table.

      It must have the type `Boolean`. If `true` is specified, all names are translated. If `false` is specified or this parameter is omitted, only terminal nodes will be translated. That latter can be useful if internal node names are used to represent support values instead of indices in the taxon list.

      See Also:
        Constant Field Values

    - #### KEY_NEXUS_COMMAND_READER_FACTORY

          static final java.lang.String KEY_NEXUS_COMMAND_READER_FACTORY

      This parameter will only be used by `NexusEventReader` and allows to define a custom command reader factory.

      It must have the type `NexusCommandReaderFactory`. If it is omitted a factory providing all command readers available in JPhyloIO will be used.

      See Also:
        Constant Field Values

    - #### KEY_CREATE_UNKNOWN_COMMAND_EVENTS

          static final java.lang.String KEY_CREATE_UNKNOWN_COMMAND_EVENTS

      This parameter can be used to specify whether special events shall be fired if the reader encounters unknown commands (e.g. NEXUS commands).

      The value should have the type `Boolean`. If `false` or no value is specified, no such events will be fired. If `true` is specified, an event for each unknown command will be created.

      See Also:
        Constant Field Values

    - #### KEY_NEXML_TOKEN_TRANSLATION_STRATEGY

          static final java.lang.String KEY_NEXML_TOKEN_TRANSLATION_STRATEGY

      This parameter will only be used by `NeXMLEventReader` and allows to define the way tokens stored in a NeXML characters block of type `standard` should be parsed.

      It must have the type `TokenTranslationStrategy`. If it is omitted `TokenTranslationStrategy.SYMBOL_TO_LABEL` will be used as the default.

      See Also:
        Constant Field Values

    - #### KEY_NEXML_TOKEN_DEFINITION_LABEL

          static final java.lang.String KEY_NEXML_TOKEN_DEFINITION_LABEL

      This parameter will only be used by `NeXMLEventWriter` and allows to define whether the token name or the label of a `SingleTokenDefinitionEvent` shall be written to the label-attribute of a state element in a NeXML characters block of type `standard` or `protein`.

      The value should have the type `Boolean`. If `false` or no value is specified, the events' label will always be written to the label attribute. If `true` is specified, the token name defined in the event will be used.

      See Also:
        Constant Field Values

    - #### KEY_NEXML_TOKEN_DEFINITION_LABEL_METADATA

          static final java.lang.String KEY_NEXML_TOKEN_DEFINITION_LABEL_METADATA

      This parameter will only be used by `NeXMLEventWriter` and allows to define whether the token name and the label of a `SingleTokenDefinitionEvent` shall be represented as metadata always, never or only if one of these properties could not be written to the label-attribute of a state element in a NeXML characters block of type `standard` or `protein`.

      It must have the type `TokenDefinitionLabelHandling`. If it is omitted `TokenDefinitionLabelHandling.NEITHER` will be used as the default.

      See Also:
        Constant Field Values

    - #### KEY_USE_OTU_LABEL

          static final java.lang.String KEY_USE_OTU_LABEL

      This parameter will be used by some `JPhyloIOEventReader`s to determine whether the label of an associated OTU should be used as a label, if none was present in an element.

      (This parameter is not recognized by `NexusEventReader`, since the NEXUS format does not differentiate between labels and IDs and requires OTUs and linked sequences or tree nodes to have identical labels.)

      The value should have the type `Boolean`. If `false` or no value is specified, the events' label will remain `null` if no label was present in the element. If `true` is specified, the OTU label will be used, if present.

      See Also:
        Constant Field Values

    - #### KEY_APPLICATION_NAME

          static final java.lang.String KEY_APPLICATION_NAME

      Identifies the name of the application generating the output. This information, as well as the application URL and version, shall be added at the beginning of formats that support this.

      The value should be a `String`.

      See Also:
        Constant Field Values

    - #### KEY_APPLICATION_VERSION

          static final java.lang.String KEY_APPLICATION_VERSION

      Identifies the version number of the application generating the output. This information, as well as the application name and URL, shall be added at the beginning of formats that support this.

      The value should be an `Object`.

      See Also:
        Constant Field Values

    - #### KEY_APPLICATION_URL

          static final java.lang.String KEY_APPLICATION_URL

      Identifies the URL of the application generating the output. This information, as well as the application name and version, shall be added at the beginning of formats that support this.

      The value should be a `String`.

      See Also:
        Constant Field Values

    - #### KEY_LINE_SEPARATOR

          static final java.lang.String KEY_LINE_SEPARATOR

      If a line separator different from that of the current operating system shall be used by a writer, it can be specified using this key. (Note that writers for XML formats will not necessarily make use of this parameter.)

      The value should be a `String`.

      See Also:
        Constant Field Values

    - #### KEY_LINE_LENGTH

          static final java.lang.String KEY_LINE_LENGTH

      Specifies the preferred line length for writers that support this.

      The value should have an integer type (e.g. `Integer`).

      See Also:
        Constant Field Values

    - #### KEY_SEQUENCE_EXTENSION_TOKEN

          static final java.lang.String KEY_SEQUENCE_EXTENSION_TOKEN

      This parameter can be used to specify that sequences with unequal lengths (in character matrix data) shall be filled up with, until all have an equal length.

      The value should have the type `String` and define the token to be used to fill up sequences. If this parameter is omitted or `null` is specified, sequences will not be filled up. Note that the specified string should only be longer than one character, if it is only used with `MatrixDataAdapter`s that provide long tokens. (`MatrixDataAdapter.containsLongTokens(ReadWriteParameterMap)` must return `true`.)

      Note that this parameter is valid for all alignments. It is not possible to extend only a subset alignments of the same file using this parameter.

      See Also:
        Constant Field Values

    - #### KEY_IGNORE_COMMENTS

          static final java.lang.String KEY_IGNORE_COMMENTS

      This parameter is reserved for future use and currently not supported by any reader or writer in JPhyloIO. It will specify whether comment events should generated by readers or comments should be ignored. If a file contains very large comments, ignoring them may lead to a performance increase.

      The value should have the type `Boolean`. If `true` is specified, comment events will be ignored by writers supporting this parameter. If `false` is specified or this parameter is omitted, comments will be written to the output at all supported positions.

      See Also:
        Constant Field Values

    - #### KEY_ALLOW_DEFAULT_NAMESPACE

          static final java.lang.String KEY_ALLOW_DEFAULT_NAMESPACE

      This parameter can be used to specify whether readers of XML formats shall also accept tags of their target format without any namespace definition.

      The value should have the type `Boolean`. If `true` or no value is specified, tags without the target format namespace declaration will be supported, if their local part fits. If `false` is specified, the correct namespace is required.

      See Also:
        Constant Field Values

    - #### KEY_MAXIMUM_NAME_LENGTH

          static final java.lang.String KEY_MAXIMUM_NAME_LENGTH

      This parameter can be used to specify a custom maximum lengths for element names. An example would be the length of sequence names in Phylip, which may be customized using this parameter.

      The value should have an integer type (e.g. `Integer`). Note that some formats may define a fixed maximum length and specifying this parameter may lead to a deviation from the standards of this format. Refer to the documentation of the according writer for details in that.

      See Also:
        Constant Field Values

    - #### KEY_GENERATE_NEXUS_TRANSLATION_TABLE

          static final java.lang.String KEY_GENERATE_NEXUS_TRANSLATION_TABLE

      This parameter can be used to specify whether a `TRANSLATE` command should be included in the `TREES` block of a Nexus document.

      The value should have the type `Boolean`. If `true` is specified, a `TRANSLATE` command will be written and references to will be used as node labels in the following tree(s). If `false` or no value is specified, the full node labels will included in the tree(s).

      See Also:
        Constant Field Values

    - #### KEY_ALWAYS_WRITE_NEXUS_NODE_LABELS

          static final java.lang.String KEY_ALWAYS_WRITE_NEXUS_NODE_LABELS

      This parameter can be used to specify whether a nodes in a Nexus TREE command should always be written as full labels of if their index in the associated TAXA block should be used, when possible.

      The value should have the type `Boolean`. If `false` or no value is specified, labels will be replaced by indices, whenever possible. If `true` is specified, the full labels will always be used.

      See Also:
        Constant Field Values

    - #### KEY_LABEL_EDITING_REPORTER

          static final java.lang.String KEY_LABEL_EDITING_REPORTER

      Writers may have to edit names of OTUs, sequences or tree/network nodes according to the limitations of a specific format. In such cases, the generated names used in the output will be registered in an information object, which will be stored in the parameter map under this key.

      The value will have the type `LabelEditingReporter`. If no instance is specified, writers supporting this key will create a new one and put it in their parameter map. If a reporter is specified, its previous contents will be cleared by the writer. If an object of another type is specified using this key, it will be replaced.

      See Also:
        `#getLabelEditingReporter()`, Constant Field Values

    - #### KEY_OBJECT_TRANSLATOR_FACTORY

          static final java.lang.String KEY_OBJECT_TRANSLATOR_FACTORY

      This parameter can be used to specify a custom instance of `ObjectTranslatorFactory` that is used by readers to create literal meta object values and writers to obtain string and XML representations of objects. Specifying a custom factory allows to provide translators for custom data types or to overwrite default translators for common types.
      See Also:
        `ReadWriteParameterMap.getObjectTranslatorFactory()`, Constant Field Values

    - #### KEY_PHYLOXML_CONSIDER_PHYLOGENY_AS_TREE

          static final java.lang.String KEY_PHYLOXML_CONSIDER_PHYLOGENY_AS_TREE

      This parameter will only be used by `PhyloXMLEventReader` and allows to define if trees read from a PhyloXML file should always be considered as trees or networks. In the first case, "clade relation" tags contained in a phylogeny will only be represented as meta information, not as additional edge events.

      The value should have the type `Boolean`. If `false` or no value is specified, a phylogeny will always be considered as a network. If `true` is specified, it will always be considered as a tree.

      See Also:
        Constant Field Values

    - #### KEY_PHYLOXML_METADATA_TREATMENT

          static final java.lang.String KEY_PHYLOXML_METADATA_TREATMENT

      This parameter will only be used by `PhyloXMLEventWriter` and allows to define which metadata events from an adapter should be written.

      The value must have the type `PhyloXMLMetadataTreatment`. If no value is specified, all metadata events will be written sequentially. A possible hierarchical structure will be lost.

      See Also:
        Constant Field Values

    - #### KEY_PHYLOXML_EVENT_ID_TRANSLATION_MAP

          static final java.lang.String KEY_PHYLOXML_EVENT_ID_TRANSLATION_MAP

      This parameter will only be used by `PhyloXMLEventReader` and allows to obtain an object that maps the IDs used in a PhyloXML document to refer to specific elements to according JPhyloIO event IDs.

      The value will have the type `Map`.

      See Also:
        Constant Field Values

    - #### KEY_CUSTOM_XML_NAMESPACE_HANDLING

          static final java.lang.String KEY_CUSTOM_XML_NAMESPACE_HANDLING

      This parameter will be used by XML writers to determine whether namespaces used or declared in customXML shall be managed together with other namespaces of the document by the used JPhyloIO writer. Managing may include changing the prefix a namespace is bound to.

      The value should have the type `Boolean`. If `false` or no value is specified, the JPhyloIO writer will not manage namespaces within custom XML elements. If `true` is specified, it will manage them.

      See Also:
        Constant Field Values