Isis Script is an Xtext-based DSL for generating Java code for the Apache Isis framework from a textual representation.
The Isis Script DSL is inspired by concepts from Domain-Driven Design. It provides keywords for creating entities (with their annotations, injections, properties, events, actions and UI hints) and services (with their annotations, injections and actions). To map the Isis Script DSL to the corresponding Java code the notion of packages and imports are supported as well.
The following example shows an entity with a property, an action publishing an event and a title UI hint:
packagedomainapp.dom.modules.simpleimportorg.apache.isis.applib.annotation.Actionimportorg.apache.isis.applib.annotation.DomainObject@DomainObject(objectType = "SIMPLE")
@Queries(#[
@Query(name = "findByName", language = "JDOQL",
value = "SELECT FROM domainapp.dom.modules.simple.SimpleObject WHERE name.indexOf(:name) >= 0")
])
entitySimpleObject {
propertyStringname@Action(domainEvent = UpdateNameDomainEvent)
actionvoidupdateName {
parameterStringnewNamebody {
setName(newName)
}
eventUpdateNameDomainEvent
}
title {
TranslatableString.tr("Object: {name}", "name", name)
}
}The following example (package and imports are omitted for brevity) shows a repository service for the aforementioned entity:
@DomainService(repositoryFor = SimpleObject)
serviceSimpleObjects {
actionList<SimpleObject> listAll {
body {
container.allInstances(SimpleObject)
}
}
actionList<SimpleObject> findByName {
@ParameterLayout(named="Name") parameterStringnamebody {
container.allMatches(newQueryDefault(SimpleObject, "findByName", "name", name))
}
}
}The following example (package and imports are omitted for brevity) shows a service with an action using an injected repository:
serviceSimpleObjectProvider {
injectSimpleObjectsrepoactionList<SimpleObject> allObjects {
body {
repo.listAll
}
}
}The following examples shows the complete Isis Script for the entity and repository service of the domain object SimpleObject from the Isis Script simpleapp example project created from the Apache Isis Maven archetype SimpleApp:
packagedomainapp.dom.modules.simpleimportjavax.jdo.annotations.Columnimportjavax.jdo.annotations.DatastoreIdentityimportjavax.jdo.annotations.IdGeneratorStrategyimportjavax.jdo.annotations.IdentityTypeimportjavax.jdo.annotations.PersistenceCapableimportjavax.jdo.annotations.Queriesimportjavax.jdo.annotations.Queryimportjavax.jdo.annotations.Uniqueimportjavax.jdo.annotations.Versionimportjavax.jdo.annotations.VersionStrategyimportorg.apache.isis.applib.annotation.Actionimportorg.apache.isis.applib.annotation.BookmarkPolicyimportorg.apache.isis.applib.annotation.DomainObjectimportorg.apache.isis.applib.annotation.DomainObjectLayoutimportorg.apache.isis.applib.annotation.Editingimportorg.apache.isis.applib.annotation.Parameterimportorg.apache.isis.applib.annotation.ParameterLayoutimportorg.apache.isis.applib.annotation.Propertyimportorg.apache.isis.applib.annotation.Titleimportorg.apache.isis.applib.services.i18n.TranslatableString@PersistenceCapable(identityType=IdentityType.DATASTORE)
@DatastoreIdentity(strategy=IdGeneratorStrategy.IDENTITY, column="id")
@Version(strategy=VersionStrategy.VERSION_NUMBER, column="version")
@Queries(#[
@Query(name = "find", language = "JDOQL",
value = "SELECT FROM domainapp.dom.modules.simple.SimpleObject"),
@Query(name = "findByName", language = "JDOQL",
value = "SELECT FROM domainapp.dom.modules.simple.SimpleObject WHERE name.indexOf(:name) >= 0")
])
@Unique(name="SimpleObject_name_UNQ", members = #["name"])
@DomainObject(objectType = "SIMPLE")
@DomainObjectLayout(bookmarking = BookmarkPolicy.AS_ROOT)
entitySimpleObject {
@Column(allowsNull="false", length = 40)
@Title(sequence="1")
@Property(editing = Editing.DISABLED)
propertyStringname@Action(domainEvent = UpdateNameDomainEvent)
actionSimpleObjectupdateName {
@Parameter(maxLength = 40)
@ParameterLayout(named = "New name")
parameterStringnewName {
default {
getName
}
}
body {
setName(newName)
this
}
validate {
if (newName.contains("!"))
TranslatableString.tr("Exclamation mark is not allowed")
elsenull
}
eventUpdateNameDomainEvent
}
title {
TranslatableString.tr("Object: {name}", "name", name)
}
}packagedomainapp.dom.modules.simpleimportorg.apache.isis.applib.annotation.DomainServiceLayoutimportorg.apache.isis.applib.annotation.DomainServiceimportorg.apache.isis.applib.annotation.Actionimportorg.apache.isis.applib.annotation.SemanticsOfimportorg.apache.isis.applib.annotation.BookmarkPolicyimportorg.apache.isis.applib.annotation.ActionLayoutimportorg.apache.isis.applib.annotation.MemberOrderimportorg.apache.isis.applib.annotation.ParameterLayoutimportorg.apache.isis.applib.query.QueryDefaultimportjava.util.List@DomainService(repositoryFor = SimpleObject)
@DomainServiceLayout(menuOrder = "10")
serviceSimpleObjects {
@Action(semantics = SemanticsOf.SAFE)
@ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
@MemberOrder(sequence = "1")
actionList<SimpleObject> listAll {
body {
container.allInstances(SimpleObject)
}
}
@Action(semantics = SemanticsOf.SAFE)
@ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
@MemberOrder(sequence = "2")
actionList<SimpleObject> findByName {
@ParameterLayout(named="Name") parameterStringnamebody {
container.allMatches(newQueryDefault(SimpleObject, "findByName", "name", name))
}
}
@MemberOrder(sequence = "3")
actionSimpleObjectcreate {
@ParameterLayout(named="Name")
parameterStringnamebody {
valobj = container.newTransientInstance(SimpleObject)
obj.name = namecontainer.persistIfNotAlready(obj)
obj
}
}
}A formal description of the Isis Script DSL can be found here.
Isis Script uses Xtexts support for accessing JVM types, e.g. for Java annotations, super types, return types or parameters.
@Action(domainEvent = UpdateNameDomainEvent)
actionSimpleObjectupdateName {
@Parameter(maxLength = 40)
@ParameterLayout(named = "New name")
parameterStringnewName {Xbase expressions are used to implement the dynamic parts of the DSL, e.g. property features, actions or UI hints.
validate {
if (newName.contains("!"))
TranslatableString.tr("Exclamation mark is not allowed")
elsenull
}Isis Script files (which are using the file name extension .isis) are representing a single Java type. Depending on the declaration type keyword (entity or service) the corresponding source code is generated in the package defined via the package keyword within the folder target/generated-sources/isis/. This source code is plain Java which is compiled by the Java compiler.
Isis Script comes with an Xtext-generated Eclipse editor which supports the IDE features known from the Java editor, e.g
- Syntax Coloring
- Outline View
- Content Assist
- Organize Imports
- Validator
- Quick Fixes
- Hyper Linking
The source code in the editor is evaluated while typing. So the outline and the problems markers are updated automatically. If enabled then selecting a node in the outline then the corresponding code block is selected in the editor view.
When a modified Isis Script is saved in the editor then the corresponding Java source file is generated within the folder target/generated-sources/isis/.
To switch between the generated Java source file and the Isis Script file the option "Open Generated File" / "Open Source File" from the editors context menu can be used.
Isis Script files are compiled to Java source code via the Xtext Maven Plugin. To add the Isis Script output folder to Mavens list of Java source folder the Build Helper Maven Plugin is used. Finally the generated Java source code is compiled by the Maven Compiler Plugin.
A corresponding Maven POM is available in the simpleapp example project.
To use Isis Script you need local installations of the following tools:
The Isis Script Editor can be installed with the Eclipse Update Manager Help > Install New Software... from the
update site https://raw.githubusercontent.com/vaulttec/isis-script/updatesite/.
Isis Script is released under the Eclipse Public License, Version 1.0.