Tuesday, July 3, 2012

Versions and Version Constraints

The following is a preview of functionality in the upcoming Sapphire 0.6 release. If you are new to Sapphire, get introduced, download the latest release and ask questions.

In many complex Sapphire models, it is useful to be able to constrain functionality based on a version. To simplify these scenarios, Sapphire now has native constructs for dealing with versions and version constraints.

Version - Represents a version as a sequence of long integers. In string format, it is represented as a dot-separated list of numeric segments, such as "1.2.3" or "".

VersionConstraint - A boolean expression that can check versions for applicability. In string format, it is represented as a comma-separated list of specific versions, closed ranges (expressed using "[1.2.3-4.5)" syntax and open ranges (expressed using "[1.2.3" or "4.5)" syntax). The square brackets indicate that the range includes the specified version. The parenthesis indicate that the range goes up to, but does not actually include the specified version.

Sapphire.version() - Determines the version of Sapphire.

Both Version and VersionConstraint classes can be used as a type of a value property.


// *** Version ***
@Type( base = Version.class )

ValueProperty PROP_VERSION = new ValueProperty( TYPE, "Version" );
Value<Version> getVersion();
void setVersion( String value );
void setVersion( Version value );
// *** VersionConstraint ***
@Type( base = VersionConstraint.class )

ValueProperty PROP_VERSION_CONSTRAINT = new ValueProperty( TYPE, "VersionConstraint" );
Value<VersionConstraint> getVersionConstraint();
void setVersionConstraint( String value );
void setVersionConstraint( VersionConstraint value );

Further, version constraints can be evaluated in an expression via a pair of new functions. The VersionMatches function takes a version as the first parameter, a version constraint as a second parameter and returns a boolean. The SapphireVersionMatches function takes a version constraint as the sole parameter, evaluates it against Sapphire version and returns a boolean.


In this example, the VersionMatches function is used to control property enablement.

// *** Provider ***
@Label( standard = "provider" )
@Enablement( expr = "${ VersionMatches( Root().Version, '[1.1' ) }" )
@XmlBinding( path = "provider" )

ValueProperty PROP_PROVIDER = new ValueProperty( TYPE, "Provider" );

Value<String> getProvider();
void setProvider( String value );


In this example, the VersionMatches function is used in sdef to control visibility of a properties view page.

        <visible-when>${ VersionMatches( Root().Version, '[1.1' ) }</visible-when>

No comments: