com.neeve.ddl

Class DdlXMLParser

java.lang.Object

com.neeve.ddl.DdlXMLParser

public final class DdlXMLParser
extends Object

Parses an x-ddl Model and converts the parsed into an X Configuration Script (XCS) that can be used to seed the configuration repository.

Ddl Property Format

While XML is the main format that the platform uses to accept application configuartion, A DDL XML document can additional be expressed in a Properties based format which has the following advantages:

• It allows overriding of configuration values at runtime via System or environment properties specified as a key/value pair.
• The properties based format facilates easier merging.
• The properties based format can be a convenient way for applications using an external configuration mechanism to translate configuration to the platform's configuration
• The x-ddl schema meanwhile provides a structured validated document format with a broard tool set for users.

The DDL property format can be derived from x-ddl schema by converting the xml format to a set of hierarchical properties derived by concatenation the xml model child elements into a '.' separated properties path prefixed by 'x.'. In cases where the a DDL element has a list of child elements the property path is formed by using either the 'name' or 'id' attribute of the child element to form a unique path. The following are examples of converting DDL XML to a properties:
For example:

 <model>
   <env>
     <nv>
       <checked>false</checked>
       <optimizefor>latency</optimizefor>
     </nv>
   </env>
   <apps>
     <app name="OrderProcessing" mainClass="com.acme.OrderProcessingApp">
       <disposeOnSend>true</disposeOnSend>
       <performDuplicateChecking>false</performDuplicateChecking>
     </app>
     <app name="Shipping" mainClass="com.acme.ShippingApp">
       <disposeOnSend>true</disposeOnSend>
       <performDuplicateChecking>true</performDuplicateChecking>
       <messaging>
         <factories>
           <factory>com.example.MessageFactory</factory>
           <factory>com.example.AdminMessageFactory</factory>
         </factories>
       </messaging>
     </app>
   </env>
 </model>
 

would translate to:

 x.env.nv.checked = false
 x.env.nv.optimizefor = latency
 x.apps.OrderProcessing.mainClass=com.acme.OrderProcessingApp
 x.apps.OrderProcessing.disposeOnSend=true
 x.apps.OrderProcessing.performDuplicateChecking=false
 x.apps.Shipping.mainClass=com.acme.ShippingApp
 x.apps.Shipping.disposeOnSend=true
 x.apps.Shipping.performDuplicateChecking=false
 x.apps.Shipping.messaging.factories.1=com.example.MessageFactory
 x.apps.Shipping.messaging.factories.2=com.example.AdminMessageFactory
 

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	ESCAPE_SUBSTITUTION_VALUES_DEFAULT Deprecated. See DdlConfigConstants.ESCAPE_SUBSTITUTION_VALUES_DEFAULT
static String	ESCAPE_SUBSTITUTION_VALUES_PROP Deprecated. See DdlConfigConstants.VALIDATE_DDL_DEFAULT
static String	PROP_VALIDATE_DDL Deprecated. See DdlConfigConstants.VALIDATE_DDL_PROPNAME
static String	PROP_VALIDATE_DDL_DEFAULT Deprecated. See DdlConfigConstants.VALIDATE_DDL_DEFAULT
static String	UNSUBSTITUTED_VARIABLE_VALUE Deprecated. This property is no longer used.

Constructor Summary

Constructors

Constructor and Description
DdlXMLParser()

Method Summary

Modifier and Type	Method and Description
static void	addProperties(com.neeve.ddl.jaxb.HierarchicalPropertySet ddlProperties, Properties properties) This method can be used to add properties to a HierarchicalPropertySet.
static com.neeve.ddl.jaxb.Model	fromDdlProperties(Properties ddlProperties, UtlTailoring.PropertySource overrides) Converts to DDL model from DDL properties format.
static com.neeve.ddl.jaxb.Model	fromDdlProperties(Properties ddlProperties, UtlTailoring.PropertySource overrides, boolean resolveProfileAndTemplates) Converts to DDL model from DDL properties format.
static com.neeve.ddl.jaxb.Model	parse(File ddl, UtlTailoring.PropertySource substitutionsAndOverrides) Parses the given File as a DDL Model.
static com.neeve.ddl.jaxb.Model	parse(InputStream descriptorInput, UtlTailoring.PropertySource substitutionsAndOverrides) Parses the given InputStream as a DDL Model.
static com.neeve.ddl.jaxb.Model	parse(String ddl, UtlTailoring.PropertySource substitutionsAndOverrides) Parses the given String into a DDL Model.
static void	parseAndAppendJvmParams(com.neeve.ddl.jaxb.XvmConfig.Provisioning.Jvm jvmConfig, Appendable target) Given a JVM config, parse the JVM Parameters and parameter sets into a JVM Parameter String.
static File	parseAndConvertToXcs(InputStream descriptorInput, boolean echo, UtlTailoring.PropertySource substitutionsAndOverrides) Parse the given descriptorFile and converts its value to an xcs script that can be used to seed the configuration repository.
static void	set(com.neeve.ddl.jaxb.HierarchicalPropertySet ddlProperties, Properties properties) This method can be used to set the properties in a HierarchicalPropertySet.
static Properties	toDdlProperties(com.neeve.ddl.jaxb.Model model) Converts a DDL model to DDL properties format.
static File	toXcs(com.neeve.ddl.jaxb.Model model) Converts a DDL model to an XCS file to apply to an X config repo
static File	toXcs(com.neeve.ddl.jaxb.Model model, boolean echo) Converts a DDL model to an XCS file to apply to an X config repo
static File	toXcs(com.neeve.ddl.jaxb.Model model, boolean echo, UtlTailoring.PropertySource overrides) Converts a DDL model to an XCS file to apply to an X config repo
static void	toXcs(com.neeve.ddl.jaxb.Model model, boolean echo, UtlTailoring.PropertySource overrides, Appendable out) Converts a DDL model to an XCS file to apply to an X config repo
static void	toXml(com.neeve.ddl.jaxb.Model model, Appendable out) Dumps the model to the given Appendable as XML.
static Properties	unmarshalProperties(com.neeve.ddl.jaxb.HierarchicalPropertySet properties) This method can be used to unmarshal a HierarchicalPropertySet into java Properties.
static void	writeSystemDetails(File srcDdlFile, File destDdlFile, com.neeve.ddl.jaxb.SystemDetails systemDetails) Rewrites systemInfo section of DDL XML with supplied map of values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_VALIDATE_DDL

@Deprecated
public static final String PROP_VALIDATE_DDL

Deprecated. See DdlConfigConstants.VALIDATE_DDL_PROPNAME

See Also:

Constant Field Values

PROP_VALIDATE_DDL_DEFAULT

@Deprecated
public static final String PROP_VALIDATE_DDL_DEFAULT

Deprecated. See DdlConfigConstants.VALIDATE_DDL_DEFAULT

See Also:

Constant Field Values

ESCAPE_SUBSTITUTION_VALUES_PROP

@Deprecated
public static final String ESCAPE_SUBSTITUTION_VALUES_PROP

Deprecated. See DdlConfigConstants.VALIDATE_DDL_DEFAULT

See Also:

Constant Field Values

ESCAPE_SUBSTITUTION_VALUES_DEFAULT

@Deprecated
public static final boolean ESCAPE_SUBSTITUTION_VALUES_DEFAULT

Deprecated. See DdlConfigConstants.ESCAPE_SUBSTITUTION_VALUES_DEFAULT

See Also:

Constant Field Values

UNSUBSTITUTED_VARIABLE_VALUE

@Deprecated
public static final String UNSUBSTITUTED_VARIABLE_VALUE

Deprecated. This property is no longer used.

See Also:

Constant Field Values

Constructor Detail

DdlXMLParser

public DdlXMLParser()

Method Detail

parseAndConvertToXcs

public static final File parseAndConvertToXcs(InputStream descriptorInput,
                                              boolean echo,
                                              UtlTailoring.PropertySource substitutionsAndOverrides)
                                       throws Exception

Parse the given descriptorFile and converts its value to an xcs script that can be used to seed the configuration repository.

This method is equivalent to calling:

• parse(descriptorInput, substitutionResolver)
• toDdlProperties(Model)
• DdlPropertyParser#toXcs(properties, echo, substitutionResolver)

Parameters:

descriptorInput - The input DDL

echo - Whether or not the XCS script has 'echo on' enabled

substitutionsAndOverrides - The resolver for substitution variables and overrides in the DDL.

Returns:

The generated XCS script

Throws:

Exception

toXcs

public static final File toXcs(com.neeve.ddl.jaxb.Model model,
                               boolean echo)
                        throws Exception

Converts a DDL model to an XCS file to apply to an X config repo

Parameters:

model - The DDL model

echo - Indicates whether the config xcs file should have 'echo on' or 'echo off' as the starting command

Throws:

Exception

toXcs

public static final File toXcs(com.neeve.ddl.jaxb.Model model,
                               boolean echo,
                               UtlTailoring.PropertySource overrides)
                        throws Exception

Converts a DDL model to an XCS file to apply to an X config repo

Parameters:

model - The DDL model

echo - Indicates whether the config xcs file should have 'echo on' or 'echo off' as the starting command

overrides - A PropertySource for overrides of xml parsed values. Override properties take precedence over values supplied via xml.

Throws:

Exception

toXcs

public static final void toXcs(com.neeve.ddl.jaxb.Model model,
                               boolean echo,
                               UtlTailoring.PropertySource overrides,
                               Appendable out)
                        throws Exception

Converts a DDL model to an XCS file to apply to an X config repo

Parameters:

model - The DDL model

echo - Indicates whether the config xcs file should have 'echo on' or 'echo off' as the starting command.

overrides - A PropertySource for overrides of xml parsed values. Override properties take precedence over values supplied via xml.

out - The appendable to which to write the xcs script.

Throws:

Exception

set

public static final void set(com.neeve.ddl.jaxb.HierarchicalPropertySet ddlProperties,
                             Properties properties)

This method can be used to set the properties in a HierarchicalPropertySet.

Examples of Properties objects in the jaxb model include:

• Model.getEnv()
• DiscoveryDescriptor.Properties
• BusConfig.Properties
• AppConfig.Storage.Icr.Bus.Properties

Parameters:

properties - The properties.

addProperties

public static final void addProperties(com.neeve.ddl.jaxb.HierarchicalPropertySet ddlProperties,
                                       Properties properties)

This method can be used to add properties to a HierarchicalPropertySet.

Examples of Properties objects in the jaxb model include:

• Model.getEnv()
• DiscoveryDescriptor.Properties
• BusConfig.Properties
• AppConfig.Storage.Icr.Bus.Properties

Parameters:

properties - The properties.

unmarshalProperties

public static final Properties unmarshalProperties(com.neeve.ddl.jaxb.HierarchicalPropertySet properties)

This method can be used to unmarshal a HierarchicalPropertySet into java Properties.

Examples of Properties objects in the jaxb model include:

• Model.getEnv()
• DiscoveryDescriptor.Properties
• BusConfig.Properties
• AppConfig.Storage.Icr.Bus.Properties

Parameters:

properties - The properties.

Returns:

Unmarshalled properties.

fromDdlProperties

public static final com.neeve.ddl.jaxb.Model fromDdlProperties(Properties ddlProperties,
                                                               UtlTailoring.PropertySource overrides)
                                                        throws Exception

Converts to DDL model from DDL properties format.

This method is equivalent to calling fromDdlProperties(ddlProperties, overrides, true).

Parameters:

ddlProperties - The parsed model.

overrides - the ddl override properties to apply to the model.

Throws:

Exception

fromDdlProperties

public static final com.neeve.ddl.jaxb.Model fromDdlProperties(Properties ddlProperties,
                                                               UtlTailoring.PropertySource overrides,
                                                               boolean resolveProfileAndTemplates)
                                                        throws Exception

Converts to DDL model from DDL properties format.

Special Properties

The following properties specified in either the provided ddlProperties or overrides augment conversion to the DDL model. Unless specified otherwise below the value in ddlOverrides takes precedence.

• DdlConfigConstants.DDL_PREFIX_PROPNAME controls the prefix used to identify DDL properties. (See
• DdlConfigConstants.DDL_PROPERTYNAME_VALIDATION_PROPNAME controls whether properties starting with the DDL prefix are checked for any unknown property names.
• DdlConfigConstants.DDL_PROFILES_PROPNAME controls which profiles should be activated when resolveProfileAndTemplates is set to true. This property is only sourced from the provided overrides.
• DdlConfigConstants.DDL_TARGETXVM_PROPNAME controls whether configuration should be resolved for a particular XVM in the model. This property is only sourced from the provided overrides.

Parameters:

ddlProperties - The parsed model.

overrides - These properties are used to override property values for properties in the resolved model, but do not cause creation of new properties ... e.g. they are only used to augment the values of the ddlProperties supplied when creating the returned model.

resolveProfileAndTemplates - When true this method will apply and remove profiles and templates in the model.

Throws:

Exception

toDdlProperties

public static final Properties toDdlProperties(com.neeve.ddl.jaxb.Model model)
                                        throws Exception

Converts a DDL model to DDL properties format.

Environment Overrides and Substitution

This method does not do any overriding of values from the environment or elsewhere nor does it any substitution of values in the model. The caller may merge in other properties on top of the return properties to override values if needed.

Parameters:

model - The parsed model.

Throws:

Exception

toXcs

public static final File toXcs(com.neeve.ddl.jaxb.Model model)
                        throws Exception

Converts a DDL model to an XCS file to apply to an X config repo

Throws:

Exception

parse

public static com.neeve.ddl.jaxb.Model parse(File ddl,
                                             UtlTailoring.PropertySource substitutionsAndOverrides)
                                      throws Exception

Parses the given File as a DDL Model.

This is equivalent to calling #parse(String, PropertySource) with the file read as a utf-8 encoded string.

Parameters:

substitutionsAndOverrides - The resolver for substitution variables and overrides in the DDL.

Returns:

The parsed Ddl Model.

Throws:

JAXBException - If there is an error loading parsing the ddl.

Exception

parse

public static com.neeve.ddl.jaxb.Model parse(InputStream descriptorInput,
                                             UtlTailoring.PropertySource substitutionsAndOverrides)
                                      throws Exception

Parses the given InputStream as a DDL Model.

This is equivalent to calling #parse(String, PropertySource) with the input stream read as a utf-8 encoded string.

Parameters:

descriptorInput - The ddl xml input stream

substitutionsAndOverrides - The resolver for substitution variables and overrides in the DDL.

Returns:

The parsed Ddl Model.

Throws:

Exception - If there is an error parsing the DDL.

parse

public static com.neeve.ddl.jaxb.Model parse(String ddl,
                                             UtlTailoring.PropertySource substitutionsAndOverrides)
                                      throws Exception

Parses the given String into a DDL Model.

Substitution variables in the ddl are substituted from the provided substitution resolver and the <env> properties in the ddl, with values from the substitution resolver taking higher precedence.

Parameters:

ddl - The ddl xml input stream

substitutionsAndOverrides - The resolver for substitution variables and overrides in the DDL.

Returns:

The parsed Ddl Model.

Throws:

Exception - If there is an error parsing the DDL.

writeSystemDetails

public static void writeSystemDetails(File srcDdlFile,
                                      File destDdlFile,
                                      com.neeve.ddl.jaxb.SystemDetails systemDetails)
                               throws IOException

Rewrites systemInfo section of DDL XML with supplied map of values. If there is already systemInfo section, only tags specified in the map will be overwritten.

Parameters:

srcDdlFile - File to rewrite

destDdlFile - Destination file into which to write. If null is given, source file will be rewritten.

systemDetails - Map of values to write into systemDetails section in DDL. Keys are tag names in systemInfo section.

Throws:

IOException - If there is an error reading or writing the DDL.

toXml

public static final void toXml(com.neeve.ddl.jaxb.Model model,
                               Appendable out)
                        throws DdlConfigException

Dumps the model to the given Appendable as XML.

Parameters:

model - The model.

out - The appendable to append to.

Throws:

DdlConfigException - if their is an error generating the xml.

parseAndAppendJvmParams

public static void parseAndAppendJvmParams(com.neeve.ddl.jaxb.XvmConfig.Provisioning.Jvm jvmConfig,
                                           Appendable target)

Given a JVM config, parse the JVM Parameters and parameter sets into a JVM Parameter String.

Parameters:

jvmConfig - The JVM Configuration.

target - The target StringBuilder to which to append