You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2014/02/10 22:27:45 UTC
svn commit: r1566750 [2/2] - in /isis/site/trunk/content: ./ applib-guide/
archetypes/ archetypes/release-notes/ components/objectstores/jdo/
components/security/shiro/ core/ core/guides/ core/images/ core/services/
getting-started/ how-tos/ how-tos2/ ...
Copied: isis/site/trunk/content/how-tos2/how-to-09-020-How-to-write-a-typical-domain-service.md (from r1559516, isis/site/trunk/content/applib-guide/domain-services/how-to-09-020-How-to-write-a-typical-domain-service.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/how-tos2/how-to-09-020-How-to-write-a-typical-domain-service.md?p2=isis/site/trunk/content/how-tos2/how-to-09-020-How-to-write-a-typical-domain-service.md&p1=isis/site/trunk/content/applib-guide/domain-services/how-to-09-020-How-to-write-a-typical-domain-service.md&r1=1559516&r2=1566750&rev=1566750&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/domain-services/how-to-09-020-How-to-write-a-typical-domain-service.md (original)
+++ isis/site/trunk/content/how-tos2/how-to-09-020-How-to-write-a-typical-domain-service.md Mon Feb 10 21:27:41 2014
@@ -1,7 +1,14 @@
Singleton & request-scoped domain services
-----------------------------------------------
-Services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+Domain services (by which we also mean repositories and factories) consist of a set
+of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework,
+and are used to centralize any domain logic that does not logically
+belong in a domain entity or value. *Isis* will automatically inject
+services into every domain entity that requests them, and into each
+other.
For convenience you can [inherit](../how-tos/how-to-01-010-How-to-have-a-domain-object-be-a-POJO.html) from `AbstractService` or one of its subclasses, but this is not mandatory.
Copied: isis/site/trunk/content/intro/getting-started/quickstart-archetype.md (from r1563903, isis/site/trunk/content/getting-started/quickstart-archetype.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/intro/getting-started/quickstart-archetype.md?p2=isis/site/trunk/content/intro/getting-started/quickstart-archetype.md&p1=isis/site/trunk/content/getting-started/quickstart-archetype.md&r1=1563903&r2=1566750&rev=1566750&view=diff
==============================================================================
--- isis/site/trunk/content/getting-started/quickstart-archetype.md (original)
+++ isis/site/trunk/content/intro/getting-started/quickstart-archetype.md Mon Feb 10 21:27:41 2014
@@ -6,7 +6,7 @@ While not quite a "kitchen-sink" example
The archetype also (from 1.4.0-SNAPSHOT onwards) demonstrates Isis' support for in-built profiling, auditing, event publishing and background actions. The last of these integrates with the Quartz scheduler, executing queued-up actions every 10 seconds.
-Running this archetype is a good way to get familiar with the structure of a not-too-complex Isis application. However, to get started with your own application, we generally recommend that you run the alternative [simple archetype](simple-archetype.html). This will generate a completely stripped back and minimal application for you to refactor and extend; you can then use this ToDo app to guide your own development.
+Running this archetype is a good way to get familiar with the structure of a not-too-complex Isis application. However, to get started with your own application, we generally recommend that you run the alternative [simple archetype](./simple-archetype.html). This will generate a completely stripped back and minimal application for you to refactor and extend; you can then use this ToDo app to guide your own development.
### Generating the App
Copied: isis/site/trunk/content/reference/services/about.md (from r1566292, isis/site/trunk/content/core/services/about.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/about.md?p2=isis/site/trunk/content/reference/services/about.md&p1=isis/site/trunk/content/core/services/about.md&r1=1566292&r2=1566750&rev=1566750&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/about.md (original)
+++ isis/site/trunk/content/reference/services/about.md Mon Feb 10 21:27:41 2014
@@ -1,36 +1,4 @@
Title: Applib Services
-common services:
-
-* [DomainObjectContainer interface](../../applib-guide/reference/DomainObjectContainer.html)
-* [Exception Recognizers](./exception-recognizers.html)
-* [Clock, Fixtures, etc](../../applib-guide/supporting-features/about.html)
-
-bookmark/memento services:
-
-* [Bookmark Service](./bookmark-service.html)
-* [Memento Service](./memento-service.html) [1.4.0-SNAPSHOT]
-* [XmlSnapshot Service](./xmlsnapshot-service.html) [1.4.0-SNAPSHOT, stub]
-
-profiling/background execution [1.4.0-snapshot]:
-
-* [Command Context / Command Service](./command-context.html)
-* [Background Service / Background Command Service](./background-service.html)
-
-publishing/auditing:
-
-* [Auditing Service](./auditing-service.html)
-* [Publishing Service](./publishing-service.html)
-
-performance tuning/co-ordination [1.4.0-snapshot]:
-
-* [QueryResultsCache](./query-results-cache.html)
-* [Scratchpad](./scratchpad.html)
-* [Bulk Interaction](./bulk-interaction.html) [stub]
-
-other:
-
-* [Settings Services](./settings-services.html)
-* [Developer Utilities Service](./developer-utilities-service.html)
-
+Go to: [documentation](../documentation.html#services)
Copied: isis/site/trunk/content/reference/services/xmlsnapshot-service.md (from r1565668, isis/site/trunk/content/core/services/xmlsnapshot-service.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/services/xmlsnapshot-service.md?p2=isis/site/trunk/content/reference/services/xmlsnapshot-service.md&p1=isis/site/trunk/content/core/services/xmlsnapshot-service.md&r1=1565668&r2=1566750&rev=1566750&view=diff
==============================================================================
--- isis/site/trunk/content/core/services/xmlsnapshot-service.md (original)
+++ isis/site/trunk/content/reference/services/xmlsnapshot-service.md Mon Feb 10 21:27:41 2014
@@ -1,6 +1,6 @@
Title: XML Snapshot Service [1.4.0-SNAPSHOT]
-> this is a stub
+The *Apache Isis* framework provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects.
### API
@@ -48,12 +48,98 @@ where:
### Usage
+> TO DOCUMENT
+
+### Usage (Deprecated)
+
+This is done using the
+`org.apache.isis.core.runtime.snapshot.XmlSnapshot` class.
+
+#### Generating an XML Snapshot
+
+The `XmlSnapshot` can be created either directly or using a builder.
+
+#### Basic Usage
+
+The standard usage is to instantiate directly.
+
+ XmlSnapshot snapshot = new XmlSnapshot(customer);
+ Element customerAsXml = snapshot.getXmlElement();
+
+This will return the Customer's fields, titles of simple references, number of items in collections.
+
+In order to use the `XmlSnapshot`, the domain object must implement `org.apache.isis.applib.snapshot.Snapshottable`. This is just a marker interface.
+
+#### Including other Elements
+
+It's also possible to instruct the `XmlSnapshot` to "walk" the object graph and include other information within the generated XML.
+
+For example:
+
+ XmlSnapshot snapshot = new XmlSnapshot(customer);
+ snapshot.include("placeOfBirth"); // (1)
+ snapshot.include("orders/product"); // (2)
+ Element customerAsXml = snapshot.getXmlElement();
+
+In (1), we indicate that we want to also navigate to another domain object represented by simple reference `"placeOfBirth"`; in (2), we indicate that we want to navigate the `"orders"` collection (presumably of `Order`s) and for each referenced `Order`, to navigate in turn its `"product"` reference (presumably to a `Product` class).
+
+Note that `XmlSnapshot` is mutable, in that calls to its `getXmlElement()` may return different XML structures based on whether additional paths have been `include()`d, or whether the state of the domain objects themselves have changed.
+
+#### Using the Fluent API
+
+An `XmlSnapshot` can also be constructed using an alternative "fluent" API:
+
+ XmlSnapshot snapshot =
+ XmlSnapshot.create(customer)
+ .includePath("placeOfBirth")
+ .include("orders/product")
+ .build();
+ Element customerAsXml = snapshot.getXmlElement();
+
+#### The SnapshottableWithInclusions interface
+
+As already mentioned, in order to be snapshotted a domain object must implement the `Snapshottable` interface. This is just a marker interface, so implementing it is trivial.
+
+Alternatively, the domain object can choose to implement the
+sub-interface, `SnapshottableWithInclusions`. This moves the
+responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:
+
+ public interface SnapshottableWithInclusions extends Snapshottable {
+ List<String> snapshotInclusions();
+ }
+
+If necessary, both approaches can be combined.
+
+#### Generating an XSD schema
+
+As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.
+
+ XmlSnapshot snapshot = ...;
+ Element customerAsXml = snapshot.getXmlElement();
+ Element customerXsd = snapshot.getXsdElement();
+
+This can be useful for some tools. Note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are `include()`'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.
+
+### Hints and Tips
+
+As an alternative to using `include()`, you might consider building a non-persisted domain object (a "view model") which can reference only the relevant information required for the snapshot.
+
+For example, if only the 5 most recent Orders for a Customer were required, a `CustomerAndRecentOrders` view model could hold a collection of just those 5 `Order`s.
+
+Typically such view models would implement `SnapshottableWithInclusions`.
+
+
### Implementation
+> TO DOCUMENT
### Registering the Service
+> TO DOCUMENT
### Related Services
+> TO DOCUMENT
+
+
Added: isis/site/trunk/content/reference/value-types.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/value-types.md?rev=1566750&view=auto
==============================================================================
--- isis/site/trunk/content/reference/value-types.md (added)
+++ isis/site/trunk/content/reference/value-types.md Mon Feb 10 21:27:41 2014
@@ -0,0 +1,253 @@
+Title: Value Types
+
+The state of any given entity is characterized by properties <!--(?)--> and
+collections <!--(?)-->. A collections is a one-to-many reference to another
+entities, while a property is either a one-to-one reference to another
+entity, or it is a value.
+
+But what's a value? Well, it's an atomic piece of state. A string is a
+value, so is a number, so is a date. Values should be designed to be
+immutable (though some system value types, such as java.util.Date,
+famously are not).
+
+*Isis* supports all the standard JDK value types, and defines a number
+of its own (eg Percentage and Color). *Isis* also allows you to define
+your own value types, such as `LastName`, or `Celsius`, or `ComplexNumber`.
+
+It's also possible to make Isis integrate with third-party
+value types. *Isis* provides one such integration, with
+[JodaTime](http://joda-time.sourceforge.net/).
+
+> **Note**
+>
+> *Isis*' support for a particular value type does not necessarily imply
+> that there is a custom widget for that type in a particular viewer.
+> Rather, it means that the state of the object can be serialized, is
+> expected to have equal-by-content semantics, and is expected to be
+> immutable. It may also be parseable from a string.
+
+
+> Also, if using the JDO/DataNucleus ObjectStore, you may also need to perform additional DataNucleus-specific configuration if you want the data to be persisted in a SQL datatype other than SQL Blob (ie a serializable byte array).
+
+
+## Built-in value types
+
+The following are the value types supported by *Isis* out-of-the-box.
+
+### JDK Types
+
+The following JDK types are supported by *Isis*.
+
+#### Primitive Types
+
+All the primitive types may be used as values: `byte`, `short`, `int`, `long`, `float`, `double`, `char`, and `boolean`.
+
+#### Wrapper Types
+
+The wrapper types for each of the primitives can also be used as value types: `java.lang.Byte`, `java.lang.Short`, `java.lang.Integer`, `java.lang.Long`, `java.lang.Float`, `java.lang.Double`, `java.lang.Character`, `java.lang.Boolean`.
+
+#### Java Classes
+
+The following java classes have value semantics and may be used as value types:
+
+- `java.lang.String`
+
+- `java.math.BigInteger` and `java.math.BigDecimal`
+
+- `java.util.Date` (date and time), `java.sql.Date` (date only), and `java.sql.Time` (time only)
+
+- `java.sql.Timestamp`
+
+- `java.awt.Image`
+
+#### JODA
+
+The following [Joda](http://joda-time.sourceforge.net/) types are also supported:
+
+- `org.joda.time.LocalDate`
+
+- `org.joda.time.LocalDateTime`
+
+- `org.joda.time.DateTime`
+
+
+#### Isis AppLib
+
+*Isis* itself also provides a number of its own value types. These are
+all in the `org.apache.applib.value` package:
+
+- `Color`
+
+- `Date` (date only), `DateTime` (date and time) and `Time` (time only)
+
+- `TimeStamp`
+
+- `Image`
+
+- `Money`
+
+- `Password`
+
+- `Percentage`
+
+
+## Custom value types
+
+In addition to the built-in value types it is also possible to define user-defined value types. This is typically done using the `@Value` annotation.
+
+The `@Value` annotation is used to provide an implementation of the `org.apache.isis.applib.adapters.ValueSemanticsProvider` interface. In turn this provides objects that allow the framework to interact with the value, specifically:
+
+- the `EncoderDecoder` is used to convert the value into and back out of serializable form
+
+ This is used by some object stores (eg the XML Object Store), for by the XML Snapshot capability <!--(see ?)-->;
+
+- the `Parser` is used to convert Strings into the value type
+
+ This is used as a fallback by viewers that do not have any specific widgets to support the particular value type, and make do with a simple text field instead.
+
+ An obvious example is to parse a date. But it could be used to parse "TRUE" and "FALSE" into a boolean (as opposed to using a checkbox).
+
+- the `DefaultsProvider` is used to provide a meaningful default for the value
+
+ Not every value type will have a default, but some do (eg false for a boolean, 0 for a number). This is used as the default value for non-`@Optional` properties and parameters.
+
+Each of these interfaces also reside in `org.apache.isis.applib.adapters`.
+
+For more details, explore the built-in types within the applib, for example `org.apache.isis.applib.value.Money`.
+
+ @Value(semanticsProviderName = "org.apache.isis.core.progmodel.facets.value.MoneyValueSemanticsProvider")
+ public class Money extends Magnitude {
+ ...
+ }
+
+where `MoneyValueSemanticsProvider` is the implementation of
+`ValueSemanticsProvider` described above.
+
+> **Note**
+>
+> Using value types generally removes the need for using `@MustSatisfy` annotation <!--(see ?)-->; the rules can
+> instead move down into a `validate()` method on the value type itself.
+
+
+## Third-party value types
+
+Third party value types can also supported, again
+through the use of a `ValueSemanticsProvider`. However, since the source code cannot be altered, the provider must be supplied using a key value in `isis.properties` configuration file.
+
+For example, the following would register a semantics provider for `org.jodatime.time.Interval` (not a built-in at the time of this writing):
+
+ isis.core.progmodel.value.org.jodatime.time.DateTime.semanticsProviderName=\
+ com.mycompany.values.JodaIntervalValueSemanticsProvider
+
+
+
+
+
+
+
+## Value formats
+
+> **note** this feature is only partially support by some viewers (eg Wicket viewer)
+
+*Isis* provides default formats for the inbuilt value types, according
+to type. These can be modified using `isis.properties`.
+
+These formats cut across the above categories; for example the byte
+format relates to both byte (primitive) and java.lang.Byte (wrapper). In
+all cases this setting can be overriden for a specific field using the
+@Mask annotation (see ?).
+
+#### Byte format
+
+The format for all bytes can be set, replacing the default format
+derived from the system, using the following property to specify a mask:
+
+ isis.value.format.byte=####
+
+The mask is used to set up a java.text.DecimalFormat formatting object
+so details of the mask format can be found in the Java documentation.
+
+#### Date Format
+
+The format for all dates can be set, replacing the default format derived from the system, using the following property to specify one of *long*, *medium*, *short*, *isolong*, *isoshort* or a mask:
+
+ isis.value.format.date=dd/MM/yy
+
+When a mask is specified it is used to set up a
+`java.text.SimpleDateFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Date/time Format
+
+The format for all date/time values can be set, replacing the default format derived from the system, using the following property to specify one of *long*, *medium*, *short*, *isolong*, *isoshort* or a mask:
+
+ isis.value.format.datetime=dd/MM/yy
+
+When a mask is specified it is used to set up a
+`java.text.SimpleDateFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Decimal format
+
+The format for `BigDecimal` values can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.decimal=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Double format
+
+The format for all double values can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.double=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Float format
+
+The format for all float values can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.float=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Integer format
+
+The format for all integers (including `BigInteger`) can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.int=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Long format
+
+The format for all long values can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.long=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Short format
+
+The format for all short values can be set, replacing the default format derived from the system, using the following property to specify a mask:
+
+ isis.value.format.short=####
+
+The mask is used to set up a `java.text.DecimalFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Time Format
+
+The format for all time values can be set, replacing the default format derived from the system, using the following property to specify one of *long*, *medium*, *short*, *isolong*, *isoshort* or a mask:
+
+ isis.value.format.time=ddMMyyyy hhmm
+
+When a mask is specified it is used to set up a
+`java.text.SimpleDateFormat` formatting object so details of the mask format can be found in the Java documentation.
+
+#### Timestamp Format
+
+The format for time stamp values can be set, replacing the default format derived from the system, using the following property to specify one of *long*, *medium*, *short*, *isolong*, *isoshort* or a mask:
+
+ isis.value.format.timestamp=hh:mm
+
+When a mask is specified it is used to set up a
+`java.text.SimpleDateFormat` formatting object so details of the mask format can be found in the Java documentation.
+