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/10/27 11:17:51 UTC
svn commit: r1634491 - in /isis/site/trunk/content: ./
components/viewers/restfulobjects/
Author: danhaywood
Date: Mon Oct 27 10:17:50 2014
New Revision: 1634491
URL: http://svn.apache.org/r1634491
Log:
RO viewer config props
Added:
isis/site/trunk/content/components/viewers/restfulobjects/honor-ui-hints.md
- copied, changed from r1634482, isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md
Modified:
isis/site/trunk/content/components/viewers/restfulobjects/custom-representations.md
isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md
isis/site/trunk/content/components/viewers/restfulobjects/suppressing-elements-of-the-representations.md
isis/site/trunk/content/documentation.md
Modified: isis/site/trunk/content/components/viewers/restfulobjects/custom-representations.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/restfulobjects/custom-representations.md?rev=1634491&r1=1634490&r2=1634491&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/restfulobjects/custom-representations.md (original)
+++ isis/site/trunk/content/components/viewers/restfulobjects/custom-representations.md Mon Oct 27 10:17:50 2014
@@ -2,4 +2,100 @@ Title: Custom Representations
{note
This API should be considered beta, as it may change in the future in response to emerging requirements
-}
\ No newline at end of file
+}
+
+The Restful Objects viewer implements the [Restful Object spec](http://restfulobjects.org), meaning that it:
+
+* defines a well-defined set of endpoint URLs as resources
+* generates a well-defined set of (JSON) representations when these resources are accessed.
+
+There are, however, a number of other "standards" for defining representations, among these:
+
+* [HAL](http://stateless.co/hal_specification.html) (Mike Kelly)
+* [Collection+JSON](http://amundsen.com/media-types/collection/) (Mike Amundsen)
+* [Siren](https://github.com/kevinswiber/siren) (Kevin Swiber)
+* [JSON API](http://jsonapi.org/) (Steve Klabnik)
+* [Hyper+JSON](https://github.com/cainus/hyper-json-spec) (Gregg Cainus)
+* [JSON-LD](https://www.w3.org/TR/json-ld/) (W3C)
+* [Hydra](http://www.markus-lanthaler.com/hydra/) (Markus Lanthaler)
+
+A good discussion about the relative merits of several of these different hypermedia formats can be found [here](https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ).
+
+While Isis' Restful Objects viewer only has "out-of-the-box" support for the representations defined in the Restful Objects spec,
+it is possible to plugin a custom representation generator that can produce any arbitrary representation.
+
+## API
+
+The API to implement is the `RepresentationService` API:
+
+ import javax.ws.rs.core.Response;
+ import org.apache.isis.applib.annotation.Programmatic;
+ import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
+ import org.apache.isis.viewer.restfulobjects.rendering.RendererContext;
+ import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.*;
+
+ /**
+ * Configure the Restful Objects viewer to emit custom representations (rather than the
+ * standard representations defined in the RO spec).
+ *
+ * <p>
+ * This interface is EXPERIMENTAL and may change in the future.
+ * </p>
+ */
+ public interface RepresentationService {
+
+ @Programmatic
+ Response objectRepresentation(
+ Context rendererContext,
+ ObjectAdapter objectAdapter);
+
+ @Programmatic
+ Response propertyDetails(
+ Context rendererContext,
+ ObjectAndProperty objectAndProperty,
+ MemberReprMode memberReprMode);
+
+ @Programmatic
+ Response collectionDetails(
+ Context rendererContext,
+ ObjectAndCollection objectAndCollection,
+ MemberReprMode memberReprMode);
+
+ @Programmatic
+ Response actionPrompt(
+ Context rendererContext,
+ ObjectAndAction objectAndAction);
+
+ @Programmatic
+ Response actionResult(
+ Context rendererContext,
+ ObjectAndActionInvocation objectAndActionInvocation,
+ ActionResultReprRenderer.SelfLink selfLink);
+
+ public static interface Context extends RendererContext {
+ ObjectAdapterLinkTo getAdapterLinkTo();
+ }
+ }
+
+Restful Objects' out-of-the-box support for Restful Objects spec uses this same API, specifically `RepresentationServiceForRestfulObjects` (in the `org.apache.isis.viewer.restfulobjects.rendering.service` package).
+
+Each of these methods provides:
+* a `RendererContext`, providing access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
+* an object representing the information to be rendered, eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
+* for members, whether the representation is in read/write mode (`MemberReprMode`)
+
+## Configuring
+
+Implement the service and register in `WEB-INF/isis.properties`, eg:
+
+ isis.services=...,\
+ com.mycompany.myservice.RepresentationServiceForMyRestApi,
+ ...
+
+This will replace the default representation.
+
+## See also
+
+If all that is required is a very simple representations (of objects), see [here](simplified-object-representation.html).
+
+Or, it is also possible to simply suppress certain elements; see [here](suppressing-elements-of-the-representation.html).
Copied: isis/site/trunk/content/components/viewers/restfulobjects/honor-ui-hints.md (from r1634482, isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md)
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/restfulobjects/honor-ui-hints.md?p2=isis/site/trunk/content/components/viewers/restfulobjects/honor-ui-hints.md&p1=isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md&r1=1634482&r2=1634491&rev=1634491&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md (original)
+++ isis/site/trunk/content/components/viewers/restfulobjects/honor-ui-hints.md Mon Oct 27 10:17:50 2014
@@ -1,5 +1,22 @@
-Title: Simplified Object Representation (1.8.0-SNAPSHOT)
+Title: Honor UI Hints (1.8.0-SNAPSHOT)
{note
-This API should be considered beta, as it may change in the future in response to emerging requirements
-}
\ No newline at end of file
+These configuration settings should be considered beta, and are likely to change in the future in response to emerging requirements.
+}
+
+By default the representations generated by Restful Objects ignore any Isis metamodel hints referring to the UI.
+In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are *not*
+eagerly embedded in the object representation.
+
+However, this behaviour can be overridden.
+
+## Global Configuration
+
+Configuring the Restful Objects viewer to honor UI hints globally is done using the
+following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+ isis.viewer.restfulobjects.honorUiHints=true
+
+## Per request
+
+This is not currently supported (though may be in the future).
Modified: isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md?rev=1634491&r1=1634490&r2=1634491&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md (original)
+++ isis/site/trunk/content/components/viewers/restfulobjects/simplified-object-representation.md Mon Oct 27 10:17:50 2014
@@ -1,5 +1,72 @@
Title: Simplified Object Representation (1.8.0-SNAPSHOT)
+> Enabling these settings makes the representations non-standard with respect to the [Restful Object spec](http://restfulobjects.org).
+
{note
-This API should be considered beta, as it may change in the future in response to emerging requirements
-}
\ No newline at end of file
+These configuration settings should be considered beta, and are likely to change in the future in response to emerging requirements
+}
+
+The representations specified by the [Restful Object spec](http://restfulobjects.org) are very rich in hypermedia
+controls and metadata, intended to support a wide variety of possible REST clients. As described [here](suppressing-elements-of-the-representations.html), it is possible to suppress various elements of these representations.
+Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat"
+object representation.
+
+The Restful Objects viewer therefore supports generating a much simpler representation of objects.
+
+## Global Configuration
+
+Configuring the Restful Objects viewer globally to generate the simple object representation is done using the
+following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+ isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+
+This generates a representation such as:
+
+ {
+ "title" : "Buy milk due by 2014-10-27",
+ "domainType" : "TODO",
+ "instanceId" : "L_0",
+ "members" : {
+ "description" : "Buy milk",
+ "category" : "Domestic",
+ "subcategory" : "Shopping",
+ "complete" : false,
+ "versionSequence" : 1,
+ "relativePriority" : 2,
+ "dueBy" : "2014-10-27",
+ "cost" : "0.75",
+ "notes" : null,
+ "attachment" : null,
+ "doc" : null
+ },
+ "links" : [
+ {
+ "rel" : "self",
+ "href" : "http://localhost:8080/restful/objects/TODO/L_0",
+ "method" : "GET",
+ "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
+ "title" : "Buy milk due by 2014-10-27"
+ },
+ {
+ "rel" : "describedby",
+ "href" : "http://localhost:8080/restful/domain-types/TODO",
+ "method" : "GET",
+ "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
+ }
+ ],
+ "extensions" : {
+ "oid" : "TODO:L_0"
+ },
+ }
+
+
+## Per request
+
+This is not currently supported (though may be in the future).
+
+## See also
+
+Rather than returning a completely different representation for objects, it is also possible to simply suppress certain elements;
+see [here](suppressing-elements-of-the-representation.html).
+
+On the other hand, if complete control over all representations is required, see [here](custom-representations.html).
Modified: isis/site/trunk/content/components/viewers/restfulobjects/suppressing-elements-of-the-representations.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/restfulobjects/suppressing-elements-of-the-representations.md?rev=1634491&r1=1634490&r2=1634491&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/restfulobjects/suppressing-elements-of-the-representations.md (original)
+++ isis/site/trunk/content/components/viewers/restfulobjects/suppressing-elements-of-the-representations.md Mon Oct 27 10:17:50 2014
@@ -1,6 +1,11 @@
Title: Suppressing Elements of the Representations (1.8.0-SNAPSHOT)
> Enabling these settings makes the representations non-standard with respect to the [Restful Object spec](http://restfulobjects.org).
+> In the future the spec may be updated to allow such extensions.
+
+{note
+These configuration settings should be considered beta, and are likely to change in the future in response to emerging requirements
+}
The representations specified by the [Restful Object spec](http://restfulobjects.org) are very rich in hypermedia
controls and metadata, intended to support a wide variety of possible REST clients. However, if an application is
@@ -29,3 +34,13 @@ where, respectively, these suppress:
* "disabledReason" json-prop for object members (on the object representation and member detail representations)
The defaults for all of these is false, meaning that the hypermedia/metadata is NOT suppressed.
+
+## Per request
+
+This is not currently supported (though may be in the future).
+
+## See also
+
+If even simpler representations (of objects) are required, see [here](simplified-object-representation.html).
+
+If complete control over all representations is required, see [here](custom-representations.html).
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1634491&r1=1634490&r2=1634491&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Mon Oct 27 10:17:50 2014
@@ -508,6 +508,7 @@ Features, configuration and UI customisa
Configuration & Customisation
+* [Honor UI hints](components/viewers/restfulobjects/honor-ui-hints.html) (1.8.0-SNAPSHOT)
* [Suppressing elements of the representations](components/viewers/restfulobjects/suppressing-elements-of-the-representations.html) (1.8.0-SNAPSHOT)
* [Simplified object representation](components/viewers/restfulobjects/simplified-object-representation.html) (1.8.0-SNAPSHOT)
* [Custom representations](components/viewers/restfulobjects/custom-representations.html)