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 2020/03/03 07:09:30 UTC
[isis] 02/02: ISIS-2062: sync examples, adds in tags for refguide
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit df9e8bc0b847fb3e485fefaf8bd083c2286ecdbc
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 3 07:08:18 2020 +0000
ISIS-2062: sync examples, adds in tags for refguide
---
.../examples/services/audit/AuditerService.java | 12 +-
.../services/audit/AuditerServiceLogging.java | 10 +-
.../examples/services/bookmark/Bookmark.java | 22 ++--
.../services/bookmark/BookmarkHolder_lookup.java | 6 +-
.../services/bookmark/BookmarkHolder_object.java | 7 +-
.../services/bookmark/BookmarkService.java | 56 +++++++--
.../services/bookmarkui/BookmarkUiService.java | 2 +-
.../examples/services/command/Command.java | 13 +-
.../examples/services/command/CommandContext.java | 13 +-
.../services/command/CommandExecutorService.java | 15 ++-
.../services/command/spi/CommandService.java | 12 +-
.../services/confview/ConfigurationMenu.java | 8 +-
.../confview/ConfigurationViewService.java | 2 +
.../services/conmap/ContentMappingService.java | 8 +-
.../examples/services/email/EmailService.java | 8 +-
.../applib-svc/examples/services/error/Ticket.java | 12 ++
.../services/exceprecog/ExceptionRecognizer.java | 62 +++++++---
.../exceprecog/ExceptionRecognizerService.java | 27 +++--
.../services/exceprecog/TranslatableException.java | 4 +
.../examples/services/factory/FactoryService.java | 52 +++++---
.../examples/services/grid/GridLoaderService.java | 10 ++
.../examples/services/grid/GridService.java | 18 +++
.../examples/services/grid/GridSystemService.java | 4 +
.../examples/services/health/Health.java | 2 +
.../examples/services/hint/HintStore.java | 8 +-
.../services/homepage/HomePageResolverService.java | 1 +
.../examples/services/homepage/package-info.java} | 13 +-
.../examples/services/i18n/TranslatableString.java | 26 +++-
.../examples/services/i18n/TranslationService.java | 57 +++++++--
.../examples/services/iactn/Interaction.java | 131 ++++++++++++++++-----
.../services/iactn/InteractionContext.java | 9 +-
.../examples/services/inject/ServiceInjector.java | 5 +
.../examples/services/jaxb/JaxbService.java | 14 ++-
.../examples/services/layout/LayoutService.java | 24 +++-
.../examples/services/linking/DeepLinkService.java | 2 +
.../services/menu/MenuBarsLoaderService.java | 4 +
.../examples/services/menu/MenuBarsService.java | 13 +-
.../examples/services/message/MessageService.java | 18 +++
.../examples/services/metamodel/DomainMember.java | 12 +-
.../examples/services/metamodel/DomainModel.java | 2 +
.../services/metamodel/MetaModelService.java | 27 +++--
.../isis/applib/services/audit/AuditerService.java | 12 +-
.../services/audit/AuditerServiceLogging.java | 10 +-
.../isis/applib/services/bookmark/Bookmark.java | 22 ++--
.../services/bookmark/BookmarkHolder_lookup.java | 6 +-
.../services/bookmark/BookmarkHolder_object.java | 7 +-
.../applib/services/bookmark/BookmarkService.java | 54 +++++++--
.../services/bookmarkui/BookmarkUiService.java | 2 +-
.../isis/applib/services/command/Command.java | 11 +-
.../applib/services/command/CommandContext.java | 5 +-
.../services/command/CommandExecutorService.java | 15 ++-
.../services/command/spi/CommandService.java | 12 +-
.../confview/ConfigurationViewService.java | 2 +
.../services/conmap/ContentMappingService.java | 8 +-
.../isis/applib/services/email/EmailService.java | 8 +-
.../apache/isis/applib/services/error/Ticket.java | 12 ++
.../services/exceprecog/ExceptionRecognizer.java | 62 +++++++---
.../exceprecog/ExceptionRecognizerService.java | 27 +++--
.../services/exceprecog/TranslatableException.java | 4 +
.../applib/services/factory/FactoryService.java | 52 +++++---
.../applib/services/grid/GridLoaderService.java | 10 ++
.../isis/applib/services/grid/GridService.java | 18 +++
.../applib/services/grid/GridSystemService.java | 4 +
.../apache/isis/applib/services/health/Health.java | 2 +
.../isis/applib/services/hint/HintStore.java | 8 +-
.../services/homepage/HomePageResolverService.java | 1 +
.../package-info.java} | 13 +-
.../applib/services/i18n/TranslatableString.java | 26 +++-
.../applib/services/i18n/TranslationService.java | 57 +++++++--
.../isis/applib/services/iactn/Interaction.java | 131 ++++++++++++++++-----
.../applib/services/iactn/InteractionContext.java | 9 +-
.../applib/services/inject/ServiceInjector.java | 5 +
.../isis/applib/services/jaxb/JaxbService.java | 14 ++-
.../isis/applib/services/layout/LayoutService.java | 24 +++-
.../applib/services/linking/DeepLinkService.java | 2 +
.../services/menu/MenuBarsLoaderService.java | 4 +
.../isis/applib/services/menu/MenuBarsService.java | 13 +-
.../applib/services/message/MessageService.java | 18 +++
.../applib/services/metamodel/DomainMember.java | 12 +-
.../applib/services/metamodel/DomainModel.java | 2 +
.../services/metamodel/MetaModelService.java | 27 +++--
.../bookmarks/BookmarkServiceDefault.java | 4 +-
82 files changed, 1069 insertions(+), 417 deletions(-)
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
index 12bcc47..5cfc02a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
@@ -42,16 +42,16 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
// tag::refguide[]
public interface AuditerService {
- boolean isEnabled(); // <1>
+ boolean isEnabled(); // <.>
void audit(
- final UUID interactionId, final int sequence, // <2>
+ final UUID interactionId, final int sequence, // <.>
final String targetClassName,
- final Bookmark target, // <3>
+ final Bookmark target, // <.>
final String memberIdentifier,
- final String propertyName, // <4>
- final String preValue, final String postValue, // <5>
- final String user, final Timestamp timestamp); // <6>
+ final String propertyName, // <.>
+ final String preValue, final String postValue, // <.>
+ final String user, final Timestamp timestamp); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
index adc9570..ebd7a23 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
@@ -59,10 +59,12 @@ public class AuditerServiceLogging implements AuditerService {
final String preValue, final String postValue,
final String user, final Timestamp timestamp) {
- String auditMessage =
- interactionId + "," + sequence + ": " +
- target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
- log.debug(auditMessage);
+ if(log.isDebugEnabled()) {
+ String auditMessage =
+ interactionId + "," + sequence + ": " +
+ target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
+ log.debug(auditMessage);
+ }
}
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
index 481db35..dc0e771 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
@@ -43,7 +43,7 @@ import lombok.val;
// tag::refguide[]
public class Bookmark implements Serializable {
-// end::refguide[]
+ // end::refguide[]
private static final long serialVersionUID = 2L;
protected static final String SEPARATOR = ":";
@@ -52,26 +52,28 @@ public class Bookmark implements Serializable {
* corresponds directly to the object's specification-id
* @see <code>RootOid</code>
*/
-// tag::refguide[]
+ // tag::refguide[]
@NonNull private final String objectType;
@NonNull private final String identifier;
-// end::refguide[]
+ // end::refguide[]
+
@Nullable private final String hintId;
-// tag::refguide[]
+ // tag::refguide[]
public static Bookmark of(String objectType, String identifier) {
return new Bookmark(objectType, identifier, /*hintId*/ null);
}
// ...
-// end::refguide[]
+ // end::refguide[]
/**
* Round-trip with {@link #toString()} representation.
*/
-// tag::refguide[]
+ // tag::refguide[]
public static Optional<Bookmark> parse(@Nullable String str) {
-// end::refguide[]
+ // end::refguide[]
+
if(str==null) {
return Optional.empty();
}
@@ -85,10 +87,10 @@ public class Bookmark implements Serializable {
}
return Optional.empty();
-// tag::refguide[]
+ // tag::refguide[]
// ...
}
-// end::refguide[]
+ // end::refguide[]
public OidDto toOidDto() {
val oidDto = new OidDto();
@@ -122,6 +124,6 @@ public class Bookmark implements Serializable {
return objectType + SEPARATOR + id;
}
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
index de4cfca..846273b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
import org.apache.isis.applib.annotation.Mixin;
import org.apache.isis.applib.annotation.SemanticsOf;
-// tag::refguide[]
@Mixin(method = "act")
public class BookmarkHolder_lookup {
@@ -42,11 +41,11 @@ public class BookmarkHolder_lookup {
@Action(
domainEvent = ActionDomainEvent.class,
semantics = SemanticsOf.SAFE
- )
+ )
@ActionLayout(
contributed = Contributed.AS_ACTION,
cssClassFa = "fa-bookmark"
- )
+ )
public Object act() {
return bookmarkService.lookup(bookmarkHolder);
}
@@ -54,4 +53,3 @@ public class BookmarkHolder_lookup {
@Inject private BookmarkService bookmarkService;
}
-// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
index 2565c2b..86b8528 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
import org.apache.isis.applib.annotation.Mixin;
import org.apache.isis.applib.annotation.SemanticsOf;
-// tag::refguide[]
@Mixin(method = "prop")
public class BookmarkHolder_object {
@@ -42,16 +41,14 @@ public class BookmarkHolder_object {
@Action(
semantics = SemanticsOf.SAFE,
domainEvent = BookmarkHolder_object.ActionDomainEvent.class
- )
+ )
@ActionLayout(
contributed = Contributed.AS_ASSOCIATION
- )
+ )
public Object prop() {
return bookmarkService.lookup(bookmarkHolder);
}
-
@Inject private BookmarkService bookmarkService;
}
-// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
index 1751729..a0ef829 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
@@ -20,6 +20,7 @@ package org.apache.isis.applib.services.bookmark;
import javax.annotation.Nullable;
+import org.apache.isis.applib.services.metamodel.MetaModelService;
import org.apache.isis.core.commons.internal.base._Casts;
import org.apache.isis.core.commons.internal.exceptions._Exceptions;
@@ -34,43 +35,76 @@ import lombok.val;
// tag::refguide[]
public interface BookmarkService {
-// end::refguide[]
+ // end::refguide[]
/**
- * Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
- * was created for.
+ * Returns the {@link Bookmark} for the given domain object.
+ *
* <p>
- * Note: Not every domain object is bookmark-able.
+ * <b>Note</b>: Not every domain object is bookmark-able: only entities, view models and services (NOT values or collections)
* </p>
- * @param domainObject
+ *
+ * @param domainObject - domain object (if any) to return a bookmark for
* @return optionally a {@link Bookmark} representing given {@code domainObject}
*/
-// tag::refguide[]
+ // tag::refguide[]
Bookmark bookmarkFor(@Nullable Object domainObject);
+ // end::refguide[]
+ /**
+ * As per {@link #bookmarkFor(Object)}, but requires that a non-null {@link Bookmark} is returned.
+ *
+ * @param domainObject - that can be bookmarked
+ * @return a (non-null) {@link Bookmark} for the provided domain object.
+ */
+ // tag::refguide[]
default Bookmark bookmarkForElseThrow(Object domainObject) {
-// end::refguide[]
+ // end::refguide[]
+
requires(domainObject, "domainObject");
val bookmark = bookmarkFor(domainObject);
if(bookmark!=null) {
return bookmark;
}
throw _Exceptions.illegalArgument(
- "cannot create bookmark for type %s", domainObject.getClass().getName());
-// tag::refguide[]
+ "cannot create bookmark for type %s", domainObject.getClass().getName());
+ // tag::refguide[]
// ...
}
+ // end::refguide[]
+ /**
+ * Utility method that creates a {@link Bookmark} from the constituent parts.
+ *
+ * @return - {@link Bookmark} for provided class and identifier
+ */
+ // tag::refguide[]
Bookmark bookmarkFor(Class<?> cls, String identifier);
+ // end::refguide[]
+ /**
+ * @see #lookup(Bookmark)
+ *
+ * @param bookmarkHolder - from which the {@link Bookmark} is obtained
+ * @return - corresponding domain object
+ */
+ // tag::refguide[]
Object lookup(BookmarkHolder bookmarkHolder);
+ // end::refguide[]
+ /**
+ * Reciprocal of {@link #bookmarkFor(Object)}
+ *
+ * @param bookmark - representing a domain object
+ * @return - the corresponding domain object
+ */
+ // tag::refguide[]
Object lookup(Bookmark bookmark);
-// end::refguide[]
+ // end::refguide[]
/**
* As {@link #lookup(Bookmark)}, but down-casting to the specified type.
*/
-// tag::refguide[]
+ // tag::refguide[]
default <T> T lookup(Bookmark bookmark, Class<T> cls) {
return cls.cast(lookup(bookmark));
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
index e21431b..d94ec32 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
@@ -23,6 +23,6 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface BookmarkUiService {
- void clear(); // <1>
+ void clear(); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
index 2d441f9..f030cb6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
@@ -105,9 +105,7 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* The date/time at which this command was created.
- *
*/
// tag::refguide[]
Timestamp getTimestamp(); // <.>
@@ -118,13 +116,13 @@ public interface Command extends HasUniqueId {
*
* <p>
* Will only be populated if a {@link BookmarkService} has been configured.
+ * </p>
*/
// tag::refguide[]
Bookmark getTarget(); // <.>
// end::refguide[]
/**
- *
* Holds a string representation of the invoked action, or the edited property, equivalent to
* {@link Identifier#toClassAndNameIdentityString()}.
*/
@@ -133,7 +131,6 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* A human-friendly description of the class of the target object.
*/
// tag::refguide[]
@@ -141,19 +138,13 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* The human-friendly name of the action invoked/property edited on the target object.
- *
- * <p>
- * NB: in earlier versions, if the command represented an edit of a property, then it held the special value "{@value ACTION_IDENTIFIER_FOR_EDIT}". This is NO LONGER the case; it simply holds the member.
- * </p>
*/
// tag::refguide[]
String getTargetAction(); // <.>
// end::refguide[]
/**
- *
* A human-friendly description of the arguments with which the action was invoked.
*/
// tag::refguide[]
@@ -390,7 +381,7 @@ public interface Command extends HasUniqueId {
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
- void setExecutor(final Executor executor);
+ void setExecutor(final Executor executor);
/**
* <b>NOT API</b>: intended to be called only by the framework.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
index 1eb6f24..2f7b4d0 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
@@ -53,7 +53,7 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class CommandContext {
-// end::refguide[]
+ // end::refguide[]
public CommandContext() {
log.debug("init");
}
@@ -68,24 +68,23 @@ public class CommandContext {
log.debug("preDestroy");
}
-// tag::refguide[]
+ // tag::refguide[]
@Getter
private Command command;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
public void setCommand(final Command command) {
this.command = command;
}
-
+
public Optional<Executor> getCurrentExecutor() {
return Optional.ofNullable(getCommand())
- .map(Command::getExecutor);
+ .map(Command::getExecutor);
}
-
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
index cfffa0a..917a4e5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
@@ -21,16 +21,25 @@ package org.apache.isis.applib.services.command;
// tag::refguide[]
public interface CommandExecutorService {
+ // end::refguide[]
+ // tag::refguide-2[]
enum SudoPolicy {
+
+ // end::refguide-2[]
/**
* For example, regular background commands.
*/
+ // tag::refguide-2[]
NO_SWITCH,
+
+ // end::refguide-2[]
/**
* For example, replayable commands.
*/
+ // tag::refguide-2[]
SWITCH,
}
+ // end::refguide-2[]
/**
* Executes the specified command.
@@ -39,7 +48,11 @@ public interface CommandExecutorService {
* @param commandWithDto
* @return - any exception raised by the command.
*/
- void executeCommand(SudoPolicy sudoPolicy, CommandWithDto commandWithDto);
+ // tag::refguide[]
+ void executeCommand(
+ SudoPolicy sudoPolicy, // <.>
+ CommandWithDto commandWithDto // <.>
+ );
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
index 8afa756..eb3abce 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
@@ -26,7 +26,7 @@ import org.apache.isis.applib.services.command.Command;
// tag::refguide[]
public interface CommandService {
-// end::refguide[]
+ // end::refguide[]
/**
* Simply instantiates the appropriate instance of the {@link Command}.
*
@@ -35,17 +35,17 @@ public interface CommandService {
* {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
* </p>
*/
-// tag::refguide[]
+ // tag::refguide[]
Command create(); // <.>
-// end::refguide[]
+ // end::refguide[]
/**
* Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
* of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
*/
-// tag::refguide[]
+ // tag::refguide[]
boolean persistIfPossible(Command command); // <.>
-// end::refguide[]
+ // end::refguide[]
/**
* "Complete" the command, typically meaning to indicate that the command is completed, and to
@@ -59,7 +59,7 @@ public interface CommandService {
* The framework will automatically have set the {@link Command#getCompletedAt()} property.
* </p>
*/
-// tag::refguide[]
+ // tag::refguide[]
void complete(final Command command); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
index cbbd0e6..7e83574 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
@@ -40,7 +40,7 @@ public class ConfigurationMenu {
// end::refguide[]
public static abstract class ActionDomainEvent
- extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
+ extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
private final ConfigurationViewService configurationService;
@@ -50,16 +50,16 @@ public class ConfigurationMenu {
}
public static class ConfigurationDomainEvent
- extends ActionDomainEvent {}
+ extends ActionDomainEvent {}
// tag::refguide[]
@Action(
domainEvent = ConfigurationDomainEvent.class,
semantics = SemanticsOf.SAFE
- )
+ )
@ActionLayout(
cssClassFa = "fa-wrench"
- )
+ )
@MemberOrder(sequence = "500.900.1")
public Set<ConfigurationProperty> configuration(){
return configurationService.allProperties();
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
index bc71130..9627c0f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
@@ -26,10 +26,12 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface ConfigurationViewService {
+ // end::refguide[]
/**
* Returns all properties, each as an instance of {@link ConfigurationProperty} (a view model).
* Mask sensitive values if required.
*/
+ // tag::refguide[]
Set<ConfigurationProperty> allProperties();
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
index c95ad15..369349e 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
@@ -30,15 +30,18 @@ import org.apache.isis.core.commons.internal.base._NullSafe;
// tag::refguide[]
public interface ContentMappingService {
+ // end::refguide[]
/**
* Typically for mapping from a domain object to a DTO.
*/
+ // tag::refguide[]
Object map(Object object, final List<MediaType> acceptableMediaTypes);
-// end::refguide[]
+ // end::refguide[]
/**
* Convenience utilities for implementations of {@link ContentMappingService}.
*/
+ // tag::refguide-2[]
public static class Util {
public static String determineDomainType(final List<MediaType> acceptableMediaTypes) {
@@ -64,7 +67,8 @@ public interface ContentMappingService {
return clazz.getName().equals(domainType);
}
}
+ // end::refguide-2[]
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
index be7f54d..e5960e7 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
@@ -37,20 +37,16 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface EmailService extends Serializable {
- /**
- * Always called by the framework, and allows the implementation to read configuration properties and initialize itself
- */
@PostConstruct
public void init() ;
- /**
- * Main API to send email and optional attachments.
- */
boolean send(List<String> to, List<String> cc, List<String> bcc, String subject, String body, DataSource... attachments);
+ // end::refguide[]
/**
* Whether this service has been configured and thus available for use.
*/
+ // tag::refguide[]
boolean isConfigured();
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
index 0d55843..dca850f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
@@ -34,10 +34,13 @@ import java.io.Serializable;
// tag::refguide[]
public interface Ticket extends Serializable {
+ // end::refguide[]
+ // tag::refguide-2[]
enum StackTracePolicy {
SHOW,
HIDE
}
+ // end::refguide-2[]
/**
* A unique identifier that the end-user can use to track any follow-up from this error.
@@ -47,8 +50,10 @@ public interface Ticket extends Serializable {
* which case the {@link #getReference() reference} would be the JIRA issue number <tt>XXX-1234</tt>.
* </p>
*/
+ // tag::refguide[]
String getReference();
+ // end::refguide[]
/**
* Message to display to the user.
*
@@ -56,8 +61,10 @@ public interface Ticket extends Serializable {
* Typically this message should be short, one line long.
* </p>
*/
+ // tag::refguide[]
String getUserMessage();
+ // end::refguide[]
/**
* Optional additional details to show to the end-user.
*
@@ -66,8 +73,10 @@ public interface Ticket extends Serializable {
* details on contacting the help desk if the issue is severe and requires immediate attention.
* </p>
*/
+ // tag::refguide[]
String getDetails();
+ // end::refguide[]
/**
* Whether the stack trace for the exception should be displayed or be hidden.
*
@@ -76,11 +85,14 @@ public interface Ticket extends Serializable {
* the support team, meaning there's no need to expose this info to the end-user.
* </p>
*/
+ // tag::refguide[]
StackTracePolicy getStackTracePolicy();
+ // end::refguide[]
/**
* Returns a Html representation of this ticket.
*/
+ // tag::refguide[]
String getMarkup();
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
index c5ca151..8c75c23 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
@@ -61,63 +61,86 @@ import lombok.val;
// tag::refguide[]
public interface ExceptionRecognizer {
+ // end::refguide[]
/**
* (Attempt to) recognize the exception and return a user-friendly
- * message to render instead.
+ * message to render instead.
*
- * @return optionally a
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
- * that describes both the
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
- * and reason that will be included with the user-friendly message.
+ * @return optionally a
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
+ * that describes both the
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
+ * and reason that will be included with the user-friendly message.
*/
+ // tag::refguide[]
Optional<Recognition> recognize(Throwable ex);
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
@RequiredArgsConstructor
enum Category {
+
+ // end::refguide-1[]
/**
* A violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
*/
+ // tag::refguide-1[]
CONSTRAINT_VIOLATION("violation of some declarative constraint"),
+
+ // end::refguide-1[]
/**
* The object to be acted upon cannot be found (404)
*/
+ // tag::refguide-1[]
NOT_FOUND("object not found"),
+
+ // end::refguide-1[]
/**
* A concurrency exception, in other words some other user has changed this object.
*/
+ // tag::refguide-1[]
CONCURRENCY("concurrent modification"),
+
+ // end::refguide-1[]
/**
* Recognized, but for some other reason... 40x error
*/
+ // tag::refguide-1[]
CLIENT_ERROR("client side error"),
+
+ // end::refguide-1[]
/**
* 50x error
*/
+ // tag::refguide-1[]
SERVER_ERROR("server side error"),
+
+ // end::refguide-1[]
/**
* Recognized, but uncategorized (typically: a recognizer of the original ExceptionRecognizer API).
*/
+ // tag::refguide-1[]
OTHER("other")
;
-
+
@Getter
private final String friendlyName;
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide-2[]
+ // tag::refguide-2[]
@Value
class Recognition {
+ // end::refguide-2[]
/**
* @return optionally a recognition of the specified type, based on a whether given reason is non-null
*/
+ // tag::refguide-2[]
public static Optional<Recognition> of(
@Nullable final Category category,
@Nullable final String reason) {
+ // end::refguide-2[]
if(reason==null) {
return Optional.empty();
@@ -125,27 +148,34 @@ public interface ExceptionRecognizer {
val nonNullCategory = category!=null? category: Category.OTHER;
return Optional.of(new Recognition(nonNullCategory, reason));
+ // tag::refguide-2[]
+ // ...
}
@NonNull private final Category category;
@NonNull private final String reason;
public String toMessage(@Nullable TranslationService translationService) {
-
+ // end::refguide-2[]
+
val categoryLiteral = translationService!=null
? translationService.translate(
ExceptionRecognizer.Category.class.getName(), getCategory().getFriendlyName())
: getCategory().getFriendlyName();
-
+
val reasonLiteral = translationService!=null
? translationService.translate(
ExceptionRecognizer.Recognition.class.getName(), getReason())
: getReason();
-
+
return String.format("[%s]: %s", categoryLiteral, reasonLiteral);
+ // tag::refguide-2[]
+ // ...
}
+ // end::refguide-2[]
}
-// end::refguide-2[]
-// tag::refguide[]
+ // end::refguide-2[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
index 64e0edd..2c8043b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
@@ -31,31 +31,38 @@ import org.apache.isis.core.commons.collections.Can;
// tag::refguide[]
public interface ExceptionRecognizerService {
+ // end::refguide[]
/**
- *
- * @return all ExceptionRecognizer implementations as discovered by the IoC container,
- * honoring order of precedence.
+ *
+ * @return all ExceptionRecognizer implementations as discovered by the IoC container,
+ * honoring order of precedence.
*/
+ // tag::refguide[]
Can<ExceptionRecognizer> getExceptionRecognizers();
+ // end::refguide[]
/**
* Takes into consideration ExceptionRecognizers as given by {@link #getExceptionRecognizers()}.
*
- * @param ex
- * @return optionally a recognition object, that describes both the category and reason,
- * that will be included with the user-friendly message.
+ * @param ex - exception to be recognized
+ * @return optionally a recognition object, that describes both the category and reason,
+ * that will be included with the user-friendly message.
*/
+ // tag::refguide[]
default Optional<Recognition> recognize(Exception ex) {
return recognizeFromSelected(getExceptionRecognizers(), ex);
}
+ // end::refguide[]
/**
* Takes into consideration ExceptionRecognizers as given by {@code recognizers}.
- * @param recognizers
- * @param ex
- * @return optionally a recognition object, that describes both the category and reason,
- * that will be included with the user-friendly message.
+ *
+ * @param recognizers - one or more recognizers to attempt to recognize the exceptoin
+ * @param ex - the exception to be recognized
+ * @return optionally a recognition object, that describes both the category and reason,
+ * that will be included with the user-friendly message.
*/
+ // tag::refguide[]
Optional<Recognition> recognizeFromSelected(Can<ExceptionRecognizer> recognizers, Exception ex);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
index 58e27e4..1e70cbc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
@@ -33,6 +33,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
// tag::refguide[]
public interface TranslatableException {
+ // end::refguide[]
/**
* In the spirit of {@link Exception#getLocalizedMessage()}, but using {@link org.apache.isis.applib.services.i18n.TranslatableString} instead.
*
@@ -43,12 +44,15 @@ public interface TranslatableException {
* accept a {@link org.apache.isis.applib.services.i18n.TranslatableString}, but can be left as null for any existing code.
* </p>
*/
+ // tag::refguide[]
TranslatableString getTranslatableMessage();
+ // end::refguide[]
/**
* The context to use when translating the {@link #getTranslatableMessage() translatable message},
* as ultimately passed through to {@link org.apache.isis.applib.services.i18n.TranslationService#translate(String, String)}.
*/
+ // tag::refguide[]
String getTranslationContext();
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
index b03a26e..e09fdf6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
@@ -23,17 +23,19 @@ import java.util.NoSuchElementException;
import javax.annotation.Nullable;
+import org.apache.isis.applib.services.repository.RepositoryService;
import org.apache.isis.core.commons.exceptions.IsisException;
// tag::refguide[]
public interface FactoryService {
+ // end::refguide[]
/**
* General purpose factory method, to automatically get or create an instance of
* {@code requiredType}.
*
* <p>
- * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
+ * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
* based on the type's meta-data.
* </p>
*
@@ -47,40 +49,48 @@ public interface FactoryService {
* @since 2.0
*
*/
+ // tag::refguide[]
<T> T getOrCreate(Class<T> requiredType);
+ // end::refguide[]
/**
- * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
- * with injection points resolved
+ * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
+ * with injection points resolved
* and any life-cycle callback processed.
- *
+ *
* @param <T>
* @param requiredType - only applicable to IoC container managed types
* @return (non-null), an instance of {@code requiredType}, if available and unique
* (i.e. not multiple candidates found with none marked as primary)
- *
+ *
* @throws NoSuchElementException if result is empty
* @throws IsisException if instance creation failed
- *
+ *
* @apiNote does not force the requiredType to be added to the meta-model
* @since 2.0
*/
+ // tag::refguide[]
<T> T get(Class<T> requiredType);
+ // end::refguide[]
/**
* Creates a new detached entity instance, with injection points resolved
* and defaults applied.
+ *
* @param <T>
* @param domainClass - only applicable to entity types
* @return
- * @throws IllegalArgumentException if domainClass is not an entity type
+ * @throws IllegalArgumentException if domainClass is not an entity type
* @apiNote forces the domainClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T detachedEntity(Class<T> domainClass);
+ // end::refguide[]
/**
* Creates a new Mixin instance, with injection points resolved.
+ *
* @param <T>
* @param mixinClass
* @param mixedIn
@@ -88,44 +98,52 @@ public interface FactoryService {
* @throws IllegalArgumentException if mixinClass is not a mixin type
* @apiNote forces the mixinClass to be added to the meta-model if not already
*/
+ // tag::refguide[]
<T> T mixin(Class<T> mixinClass, Object mixedIn);
+ // end::refguide[]
/**
- * Creates a new ViewModel instance, with injection points resolved,
- * and initialized according to the given {@code mementoStr}
+ * Creates a new ViewModel instance, with injection points resolved,
+ * and initialized according to the given {@code mementoStr}
+ *
* @param viewModelClass
* @param mementoStr - ignored if {@code null}
* @throws IllegalArgumentException if viewModelClass is not a viewmodel type
* @apiNote forces the viewModelClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T viewModel(Class<T> viewModelClass, @Nullable String mementoStr);
+ // end::refguide[]
/**
- * Creates a new ViewModel instance,
+ * Creates a new ViewModel instance,
* with injection points resolved
- * and defaults applied.
+ * and defaults applied.
* @param viewModelClass
* @throws IllegalArgumentException if viewModelClass is not a viewmodel type
* @apiNote forces the viewModelClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
default <T> T viewModel(Class<T> viewModelClass) {
return viewModel(viewModelClass, /*mementoStr*/null);
}
+ // end::refguide[]
/**
- * Creates a new instance of the specified class,
+ * Creates a new instance of the specified class,
* with injection points resolved
* and defaults applied.
* @param domainClass - not applicable to IoC container managed types
- * @throws IllegalArgumentException if domainClass is an IoC container managed type,
+ * @throws IllegalArgumentException if domainClass is an IoC container managed type,
* or not recognized by the meta-model
* @apiNote forces the domainClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T create(Class<T> domainClass);
-// end::refguide[]
+ // end::refguide[]
// -- DEPRECATIONS
@@ -156,8 +174,8 @@ public interface FactoryService {
* alternatively just <i>new()</i> up the object rather than call this
* method.
* </p>
- * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
- * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
+ * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
+ * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
* if applicable
*/
@Deprecated
@@ -165,6 +183,6 @@ public interface FactoryService {
return getOrCreate(domainClass);
}
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
index 7828441..202eb65 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
@@ -24,31 +24,41 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridLoaderService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* To support metamodel invalidation/rebuilding of spec.
*/
+ // tag::refguide[]
void remove(Class<?> domainClass);
+ // end::refguide[]
/**
* Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
*/
+ // tag::refguide[]
boolean existsFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass, String layout);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
index bdfa20a..f9db3c5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
@@ -29,32 +29,43 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* To support metamodel invalidation/rebuilding of spec.
*/
+ // tag::refguide[]
void remove(Class<?> domainClass);
+ // end::refguide[]
/**
* Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
*/
+ // tag::refguide[]
boolean existsFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a default grid; eg where none can be loaded using {@link #load(Class)}.
*/
+ // tag::refguide[]
Grid defaultGridFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a normalized grid for the domain class obtained previously using {@link #load(Class)}.
*
@@ -69,8 +80,10 @@ public interface GridService {
* <code>layout.xml</code> file takes precedence over any annotations.
* </p>
*/
+ // tag::refguide[]
Grid normalize(final Grid grid);
+ // end::refguide[]
/**
* Modifies the provided {@link Grid} with additional metadata, broadly speaking corresponding to the
* {@link DomainObjectLayout}, {@link ActionLayout}, {@link PropertyLayout} and {@link CollectionLayout}.
@@ -81,8 +94,10 @@ public interface GridService {
* to be required in the domain class itself.
* </p>
*/
+ // tag::refguide[]
Grid complete(Grid grid);
+ // end::refguide[]
/**
* Modifies the provided {@link Grid}, removing all metadata except the basic grid structure.
*
@@ -95,12 +110,15 @@ public interface GridService {
* @param grid
* @return
*/
+ // tag::refguide[]
Grid minimal(Grid grid);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>[domainClass].layout.[layout].xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(Class<?> domainClass, String layout);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
index bdeab5d..5a2c289 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
@@ -27,9 +27,11 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridSystemService<G extends Grid> {
+ // end::refguide[]
/**
* Which grid (implementation) is defined by this service.
*/
+ // tag::refguide[]
Class<G> gridImplementation();
String tns();
@@ -38,10 +40,12 @@ public interface GridSystemService<G extends Grid> {
G defaultGrid(Class<?> domainClass);
+ // end::refguide[]
/**
* Validate the grid, derive any missing object members, and overwrite any facets in the metamodel based on the
* layout.
*/
+ // tag::refguide[]
void normalize(G grid, Class<?> domainClass);
void complete(G grid, Class<?> domainClass);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
index 82c7dda..c908630 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
@@ -21,6 +21,7 @@ package org.apache.isis.applib.services.health;
import lombok.AllArgsConstructor;
import lombok.Getter;
+// tag::refguide[]
@AllArgsConstructor
public class Health {
@@ -41,3 +42,4 @@ public class Health {
public boolean getResult() { return message == null; }
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
index da2d21e..8572827 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
@@ -26,13 +26,13 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
// tag::refguide[]
public interface HintStore {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
interface HintIdProvider {
String hintId();
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
+ // tag::refguide[]
String get(final Bookmark bookmark, String hintKey);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
index 263ae0e..a4a7f6b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
@@ -22,6 +22,7 @@ import org.apache.isis.applib.annotation.HomePage;
/**
* Returns a view model annotated with {@link HomePage}.
+ *
* @since 2.0
*/
// tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
similarity index 77%
copy from api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
copy to api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
index 0ba797f..2bb38af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
@@ -16,12 +16,9 @@
* specific language governing permissions and limitations
* under the License.
*/
-package org.apache.isis.applib.services.metamodel;
-import java.util.List;
-
-public interface DomainModel {
-
- List<DomainMember> getDomainMembers();
-
-}
+/**
+ * The {@link org.apache.isis.applib.services.homepage.HomePageResolverService} returns the view model, if any
+ * annotated with {@link org.apache.isis.applib.annotation.HomePage}.
+ */
+package org.apache.isis.applib.services.homepage;
\ No newline at end of file
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
index 8f8f1f9..30de466 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.Programmatic;
import org.apache.isis.applib.annotation.Value;
import org.apache.isis.core.commons.internal.collections._Lists;
+// tag::refguide[]
@Value
public final class TranslatableString {
+ // end::refguide[]
// -- tr, trn (factory methods); constructor
/**
@@ -39,15 +41,22 @@ public final class TranslatableString {
* @param pattern - pattern for all (singular and plural) form, with <code>${xxx}</code> placeholders
* @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
*/
+ // tag::refguide[]
public static TranslatableString tr(
final String pattern,
final Object... paramArgs) {
+ // end::refguide[]
+
if(pattern == null) {
return null;
}
return new TranslatableString(Type.TR, pattern, null, 1, asMap(paramArgs));
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* A translatable string with different patterns for singular and plural forms, selected automatically by the number
*
@@ -56,14 +65,20 @@ public final class TranslatableString {
* @param number - whether to use singular or plural form when rendering
* @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
*/
+ // tag::refguide[]
public static TranslatableString trn(
final String singularPattern,
final String pluralPattern,
final int number,
final Object... paramArgs) {
+
return new TranslatableString(Type.TRN, singularPattern, pluralPattern, number, asMap(paramArgs));
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* Converts a list of objects [a, 1, b, 2] into a map {a -> 1; b -> 2}
*/
@@ -181,8 +196,9 @@ public final class TranslatableString {
* @param context
* @return
*/
- @Programmatic
+ // tag::refguide[]
public String translate(final TranslationService translationService, final String context) {
+
final String translatedText =
!isPluralForm()
? translationService.translate(context, getSingularText())
@@ -190,6 +206,7 @@ public final class TranslatableString {
return translated(translatedText);
}
+ // end::refguide[]
/**
* The text to be translated; depends on whether {@link #isPluralForm()} and whether to be translated.
*
@@ -203,10 +220,11 @@ public final class TranslatableString {
* {@link Exception#getMessage() message} when only a translatable message has been provided.
* </p>
*/
- @Programmatic
+ // tag::refguide[]
public String getPattern() {
return !isPluralForm() || number == 1 ? getSingularText() : getPluralText();
}
+ // end::refguide[]
String translated(final String translatedText) {
return format(translatedText, argumentsByParameterName);
@@ -269,6 +287,6 @@ public final class TranslatableString {
return type.toString(this);
}
-
-
+ // tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
index 17e791e..5f55e2f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
@@ -24,6 +24,7 @@ import java.util.function.Predicate;
// tag::refguide[]
public interface TranslationService {
+ // end::refguide[]
/**
* Return a translation of the text, in the locale of the "current user".
*
@@ -35,8 +36,10 @@ public interface TranslationService {
* @param text
* @return
*/
+ // tag::refguide[]
String translate(final String context, final String text);
+ // end::refguide[]
/**
* Return a translation of either the singular or the plural text, dependent on the <tt>num</tt> parameter,
* in the locale of the "current user".
@@ -51,23 +54,48 @@ public interface TranslationService {
* @param num - whether to return the translation of the singular (if =1) or of the plural (if != 1)
* @return
*/
+ // tag::refguide[]
String translate(final String context, final String singularText, final String pluralText, int num);
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Mode {
- DISABLED(configValue->configValue != null &&
- ("disable".equalsIgnoreCase(configValue) ||
- "disabled".equalsIgnoreCase(configValue))),
+
+ DISABLED (
+ // end::refguide-1[]
+ configValue->
+ ("disable".equalsIgnoreCase(configValue) ||
+ "disabled".equalsIgnoreCase(configValue))
+ // tag::refguide-1[]
+ // ...
+ ),
// synonym, needs to be defined, such that config beans (since 2.0) do work
- DISABLE(configValue->false),
+ DISABLE(
+ // end::refguide-1[]
+ configValue->false
+ // tag::refguide-1[]
+ // ...
+ ),
+
+ READ(
+ // end::refguide-1[]
+ configValue->
+ ("read".equalsIgnoreCase(configValue) ||
+ "reader".equalsIgnoreCase(configValue))
+ // tag::refguide-1[]
+ // ...
+ ),
- READ(configValue->configValue != null &&
- ("read".equalsIgnoreCase(configValue) ||
- "reader".equalsIgnoreCase(configValue))),
- // default
- WRITE(configValue->!READ.matches(configValue) && !DISABLED.matches(configValue));
+ WRITE(
+ // end::refguide-1[]
+ configValue ->
+ !READ.matches(configValue) &&
+ !DISABLED.matches(configValue)
+ // tag::refguide-1[]
+ // ...
+ );
+ // end::refguide-1[]
// -- handle values from configuration
@@ -90,9 +118,10 @@ public interface TranslationService {
public boolean isDisabled() {
return this == DISABLED || this == DISABLE;
}
+
+ // tag::refguide-1[]
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
/**
* Whether this implementation is operating in read or in write mode.
@@ -112,6 +141,8 @@ public interface TranslationService {
* such that all pathways are exercised..
* </p>
*/
+ // tag::refguide[]
Mode getMode();
+
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
index 65a2112..c65f26f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
@@ -84,11 +84,12 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class Interaction implements HasUniqueId {
-
@Getter @Setter
private UUID uniqueId;
+ // end::refguide[]
private final List<Execution<?,?>> executionGraphs = _Lists.newArrayList();
+
/**
* Returns a (list of) {@link Execution}s in the order that they were pushed. Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
*
@@ -105,23 +106,33 @@ public class Interaction implements HasUniqueId {
* {@link #execute(MemberExecutor, ActionInvocation, ClockService, MetricsService)} for us, to ensure that the
* graph is populated, but then delegate to the PublisherService immediately at the end... ie {@link org.apache.isis.schema.ixn.v2.InteractionDto}s are published as we go, not all in a batch at the end.
*/
+ // tag::refguide[]
public List<Execution<?,?>> getExecutions() {
+ // end::refguide[]
+
return Collections.unmodifiableList(executionGraphs);
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* The current (most recently pushed) {@link Execution}.
*/
+ // tag::refguide[]
@Getter
private Execution<?,?> currentExecution;
+ // end::refguide[]
/**
* The execution that preceded the current one.
*/
+ // tag::refguide[]
@Getter
private Execution<?,?> priorExecution;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*
@@ -270,51 +281,69 @@ public class Interaction implements HasUniqueId {
}
-// tag::refguide-1[]
/**
* Enumerates the different reasons why multiple occurrences of a certain type might occur within a single
* (top-level) interaction.
*/
+ // tag::refguide-1[]
public enum Sequence {
+ // end::refguide-1[]
/**
* Each interaction is either an action invocation or a property edit. There could be multiple of these,
* typically as the result of a nested calls using the {@link WrapperFactory}. Another reason is
* support for bulk action invocations within a single transaction.
*/
+ // tag::refguide-1[]
INTERACTION,
+
+ // end::refguide-1[]
/**
* For objects: multiple such could be dirtied and thus published as separate events. For actions
* invocations/property edits : multiple sub-invocations could occur if sub-invocations are made through the
* {@link WrapperFactory}.
*/
+ // tag::refguide-1[]
PUBLISHED_EVENT,
+
+ // end::refguide-1[]
/**
* There may be multiple transactions within a given interaction.
*/
+ // tag::refguide-1[]
TRANSACTION,
;
+ // end::refguide-1[]
public String id() {
return Interaction.Sequence.class.getName() + "#" + name();
}
+ // tag::refguide-1[]
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide[]
+ // tag::refguide[]
private final Map<String, LongAdder> maxBySequence = _Maps.newHashMap();
+ // end::refguide[]
/**
- * Generates numbers in a named sequence. The name of the sequence can be arbitrary, though note that the
- * framework also uses this capability to generate sequence numbers corresponding to the sequences enumerated by
- * the {@link Sequence} enum.
+ * Generates numbers in a named sequence.
+ *
+ * The name of the sequence can be arbitrary, though note that the framework also uses this capability to
+ * generate sequence numbers corresponding to the sequences enumerated by the {@link Sequence} enum.
*/
+ // tag::refguide[]
public int next(final String sequenceId) {
+ // end::refguide[]
+
final LongAdder adder = maxBySequence.computeIfAbsent(sequenceId, this::newAdder);
adder.increment();
return adder.intValue();
+
+ // tag::refguide[]
+ // ...
}
-// end::refguide[]
+ // end::refguide[]
private LongAdder newAdder(String ignore) {
final LongAdder adder = new LongAdder();
@@ -322,38 +351,46 @@ public class Interaction implements HasUniqueId {
return adder;
}
-// tag::refguide-2[]
/**
* Represents an action invocation/property edit as a node in a call-stack execution graph, with sub-interactions
* being made by way of the {@link WrapperFactory}).
*/
+ // tag::refguide-2[]
public static abstract class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
- // -- fields, constructor
-
@Getter
private final Interaction interaction;
@Getter
private final InteractionType interactionType;
@Getter
private final String memberIdentifier;
+
+ // end::refguide-2[]
/**
* The target of the action invocation. If this interaction is for a mixin action, then will be the
* mixed-in target (not the transient mixin itself).
*/
+ // tag::refguide-2[]
@Getter
private final Object target;
+
+ // end::refguide-2[]
/**
* A human-friendly description of the class of the target object.
*/
+ // tag::refguide-2[]
@Getter
private final String targetClass;
+
+ // end::refguide-2[]
/**
* The human-friendly name of the action invoked/property edited on the target object.
*/
+ // tag::refguide-2[]
@Getter
private final String targetMember;
+ // end::refguide-2[]
protected Execution(
final Interaction interaction,
final InteractionType interactionType,
@@ -377,9 +414,11 @@ public class Interaction implements HasUniqueId {
/**
* The action/property that invoked this action/property edit (if any).
*/
+ // tag::refguide-2[]
@Getter
private Execution<?,?> parent;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -393,13 +432,17 @@ public class Interaction implements HasUniqueId {
/**
* The actions/property edits made in turn via the {@link WrapperFactory}.
*/
+ // tag::refguide-2[]
public List<Execution<?,?>> getChildren() {
- return Collections.unmodifiableList(children);
- }
+ // end::refguide-2[]
+ return Collections.unmodifiableList(children);
- // -- event
+ // tag::refguide-2[]
+ // ...
+ }
+ // end::refguide-2[]
/**
* The domain event fired on the {@link EventBusService event bus} representing the execution of
* this action invocation/property edit.
@@ -410,9 +453,11 @@ public class Interaction implements HasUniqueId {
* {@link AbstractDomainEvent.Phase#EXECUTING executing} phase.
* </p>
*/
+ // tag::refguide-2[]
@Getter
private E event;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -420,29 +465,35 @@ public class Interaction implements HasUniqueId {
this.event = event;
}
-
- // -- startedAt, completedAt
-
/**
* The date/time at which this execution started.
*/
+ // tag::refguide-2[]
@Getter
private Timestamp startedAt;
+ // end::refguide-2[]
/**
* The date/time at which this execution completed.
*/
+ // tag::refguide-2[]
@Getter
private Timestamp completedAt;
public Timestamp start(
final ClockService clockService,
final MetricsService metricsService) {
+ // end::refguide-2[]
+
val startedAt = clockService.nowAsJavaSqlTimestamp();
syncMetrics(When.BEFORE, startedAt, metricsService);
return startedAt;
+
+ // tag::refguide-2[]
+ // ...
}
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -452,7 +503,6 @@ public class Interaction implements HasUniqueId {
syncMetrics(When.AFTER, completedAt, metricsService);
}
-
/**
* The object returned by the action invocation/property edit.
*
@@ -464,9 +514,11 @@ public class Interaction implements HasUniqueId {
* For <tt>void</tt> methods and for actions returning collections, the value
* will be <tt>null</tt>.
*/
+ // tag::refguide-2[]
@Getter
private Object returned;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -474,9 +526,11 @@ public class Interaction implements HasUniqueId {
this.returned = returned;
}
+ // tag::refguide-2[]
@Getter
private Exception threw;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -496,10 +550,11 @@ public class Interaction implements HasUniqueId {
* {@link Execution#getReturned()}) will (obviously) still be null.
* </p>
*/
+ // tag::refguide-2[]
@Getter
private T dto;
-
+ // end::refguide-2[]
/**
* <b>NOT API</b>: Set by framework (implementation of {@link MemberExecutor})
*/
@@ -508,12 +563,13 @@ public class Interaction implements HasUniqueId {
}
-
// -- helpers (syncMetrics)
-// tag::refguide-2a[]
+ // tag::refguide-2a[]
enum When {
BEFORE {
+ // end::refguide-2a[]
+
@Override
void syncMetrics(
final Execution<?, ?> execution,
@@ -533,8 +589,12 @@ public class Interaction implements HasUniqueId {
numberObjectsDirtiedFor(objectCountsDto).setBefore(numberObjectsDirtied);
}
+ // tag::refguide-2a[]
+ // ....
},
AFTER {
+ // end::refguide-2a[]
+
@Override void syncMetrics(
final Execution<?, ?> execution,
final Timestamp timestamp,
@@ -553,7 +613,10 @@ public class Interaction implements HasUniqueId {
numberObjectsDirtiedFor(objectCountsDto).setAfter(numberObjectsDirtied);
}
+ // tag::refguide-2a[]
+ // ....
};
+ // end::refguide-2a[]
// -- helpers
@@ -582,7 +645,10 @@ public class Interaction implements HasUniqueId {
final Timestamp timestamp,
final int numberObjectsLoaded,
final int numberObjectsDirtied);
+ // tag::refguide-2a[]
}
+ // end::refguide-2a[]
+
private void syncMetrics(
final When when,
final Timestamp timestamp,
@@ -593,16 +659,17 @@ public class Interaction implements HasUniqueId {
when.syncMetrics(this, timestamp, numberObjectsLoaded, numberObjectsDirtied);
}
-// end::refguide-2a[]
+ // tag::refguide-2[]
}
-// end::refguide-2[]
+ // end::refguide-2[]
-// tag::refguide-3[]
+ // tag::refguide-3[]
public static class ActionInvocation extends Execution<ActionInvocationDto, ActionDomainEvent<?>> {
@Getter
private final List<Object> args;
+ // end::refguide-3[]
public ActionInvocation(
final Interaction interaction,
@@ -614,14 +681,17 @@ public class Interaction implements HasUniqueId {
super(interaction, InteractionType.ACTION_INVOCATION, memberId, target, targetMember, targetClass);
this.args = args;
}
+ // tag::refguide-3[]
+ // ...
}
-// end::refguide-3[]
+ // end::refguide-3[]
-// tag::refguide-4[]
+ // tag::refguide-4[]
public static class PropertyEdit extends Execution<PropertyEditDto, PropertyDomainEvent<?,?>> {
@Getter
private final Object newValue;
+ // end::refguide-4[]
public PropertyEdit(
final Interaction interaction,
@@ -633,9 +703,12 @@ public class Interaction implements HasUniqueId {
super(interaction, InteractionType.PROPERTY_EDIT, memberId, target, targetMember, targetClass);
this.newValue = newValue;
}
+
+ // tag::refguide-4[]
+ // ...
}
-// end::refguide-4[]
+ // end::refguide-4[]
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
index a3899aa..b51c596 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
@@ -51,7 +51,7 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class InteractionContext {
-// end::refguide[]
+ // end::refguide[]
public InteractionContext() {
log.debug("init");
}
@@ -66,13 +66,13 @@ public class InteractionContext {
log.debug("preDestroy");
}
-// tag::refguide[]
/**
* The currently active {@link Interaction} for this thread.
*/
+ // tag::refguide[]
@Getter
private Interaction interaction;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
@@ -80,6 +80,7 @@ public class InteractionContext {
public void setInteraction(final Interaction interaction) {
this.interaction = interaction;
}
-// tag::refguide[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
index ea7e137..dcfee4a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
@@ -39,6 +39,8 @@ public interface ServiceInjector {
<T> T injectServicesInto(final T domainObject, Consumer<InjectionPoint> onNotResolvable);
default <T> T injectServicesInto(final T domainObject) {
+ // end::refguide[]
+
return injectServicesInto(domainObject, injectionPoint->{
val injectionPointName = injectionPoint.toString();
@@ -51,6 +53,9 @@ public interface ServiceInjector {
throw new NoSuchElementException(msg);
});
+ // tag::refguide[]
+ // ...
}
+
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
index ad86f6a..61bafdc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
@@ -47,14 +47,18 @@ public interface JaxbService {
Object fromXml(JAXBContext jaxbContext, String xml, Map<String,Object> unmarshallerProperties);
+ // end::refguide[]
/**
* As {@link #fromXml(JAXBContext, String)}, but downcast to a specific type.
*/
+ // tag::refguide[]
<T> T fromXml(Class<T> domainClass, String xml);
+ // end::refguide[]
/**
* As {@link #fromXml(JAXBContext, String, Map)}, but downcast to a specific type.
*/
+ // tag::refguide[]
<T> T fromXml(Class<T> domainClass, String xml, Map<String,Object> unmarshallerProperties);
String toXml(final Object domainObject);
@@ -75,10 +79,11 @@ public interface JaxbService {
* <a href="http://isis.apache.org/schema">downloaded</a> from the Isis website.
* </p>
*/
+ // tag::refguide[]
enum IsisSchemas {
INCLUDE,
IGNORE;
-// end::refguide[]
+ // end::refguide[]
/**
* Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
@@ -90,12 +95,12 @@ public interface JaxbService {
return namespaceUri.matches(".*isis\\.apache\\.org.*");
}
}
-// tag::refguide[]
+ // tag::refguide[]
}
Map<String, String> toXsd(final Object domainObject, final IsisSchemas isisSchemas);
-// end::refguide[]
+ // end::refguide[]
class Simple implements JaxbService {
@Override
@@ -245,6 +250,7 @@ public interface JaxbService {
}
}
}
-// tag::refguide[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
index 598cc6c..a0fb471 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
@@ -25,15 +25,17 @@ import org.apache.isis.applib.services.menu.MenuBarsService;
// tag::refguide[]
public interface LayoutService {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+
/**
* Mode of operation when downloading a layout file (while prototyping). It affects the way the file's
* content is assembled. Once a layout file is in place, its layout data takes precedence over any
* conflicting layout data from annotations.
*/
+ // tag::refguide-1[]
enum Style {
+ // end::refguide-1[]
/**
* The current layout for the domain class.
* <p>
@@ -43,8 +45,10 @@ public interface LayoutService {
* {@link org.apache.isis.applib.services.grid.GridService#defaultGridFor(Class) default grid},
* also {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
*/
+ // tag::refguide-1[]
CURRENT,
+ // end::refguide-1[]
/**
* As per {@link #NORMALIZED}, but also with all (non-null) facets for all
* properties/collections/actions also included included in the grid.
@@ -56,13 +60,15 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>serialized as XML</b></li>
* </ul>
*/
+ // tag::refguide-1[]
COMPLETE,
+ // end::refguide-1[]
/**
* Default, whereby missing properties/collections/actions are added to regions,
* and unused/empty regions are removed/trimmed.
* <p>
- * It should be possible to remove any {@link MemberOrder} and {@link MemberGroupLayout} annotation but
+ * It should be possible to remove any {@link MemberOrder} annotation but
* any property/collection/action layout annotations would need to be retained.
* <ul>
* <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
@@ -70,8 +76,10 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
* </ul>
*/
+ // tag::refguide-1[]
NORMALIZED,
+ // end::refguide-1[]
/**
* As per {@link #NORMALIZED}, but with no properties/collections/actions.
* <p>
@@ -83,25 +91,31 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
* </ul>
*/
+ // tag::refguide-1[]
MINIMAL
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide[]
+ // end::refguide[]
/**
* Obtains the serialized XML form of the layout (grid) for the specified domain class.
*/
+ // tag::refguide[]
String toXml(Class<?> domainClass, Style style);
+ // end::refguide[]
/**
* Obtains a zip file of the serialized XML of the layouts (grids) of all domain entities and view models.
*/
+ // tag::refguide[]
byte[] toZip(final Style style);
+ // end::refguide[]
/**
* Obtains the serialized XML form of the menu bars layout ({@link MenuBarsService}).
* @param type - either the current menubars (could be loaded from a file) or the fallback (obtained from metamodel facets)
*/
+ // tag::refguide[]
String toMenuBarsXml(final MenuBarsService.Type type);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
index 963eafe..ef3ef9c 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
@@ -33,10 +33,12 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface DeepLinkService {
+ // end::refguide[]
/**
* Creates a URI that can be used to obtain a representation of the provided domain object in one of the
* Isis viewers.
*/
+ // tag::refguide[]
URI deepLinkFor(Object domainObject);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
index baadf11..5ca9688 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
@@ -24,14 +24,18 @@ import org.apache.isis.applib.layout.menubars.bootstrap3.BS3MenuBars;
// tag::refguide[]
public interface MenuBarsLoaderService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* Returns a new instance of a {@link BS3MenuBars}, else <tt>null</tt>.
*/
+ // tag::refguide[]
BS3MenuBars menuBars();
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
index 940d762..10197af 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
@@ -23,29 +23,34 @@ import org.apache.isis.applib.layout.menubars.MenuBars;
// tag::refguide[]
public interface MenuBarsService {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Type {
+ // end::refguide-1[]
/**
* Either derived from annotations or as obtained elsewhere
* (eg using the {@link MenuBarsLoaderService} if the
* default implementation of this service is in use).
*/
+ // tag::refguide-1[]
DEFAULT,
+ // end::refguide-1[]
/**
* As derived from annotations.
*/
+ // tag::refguide-1[]
FALLBACK
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
+
/**
* Returns {@link #menuBars()} with a type of {@link Type#DEFAULT}.
* @return
*/
+ // tag::refguide[]
default MenuBars menuBars() {
return menuBars(Type.DEFAULT);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
index dcfc3dc..b2e32d6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
@@ -25,6 +25,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
// tag::refguide[]
public interface MessageService {
+ // end::refguide[]
/**
* Make the specified message available to the user. Note this will probably
* be displayed in transitory fashion, so is only suitable for useful but
@@ -34,8 +35,10 @@ public interface MessageService {
* @see #warnUser(String)
* @see #raiseError(String)
*/
+ // tag::refguide[]
void informUser(String message);
+ // end::refguide[]
/**
* Make the specified message available to the user, translated (if possible) to user's locale.
*
@@ -49,13 +52,17 @@ public interface MessageService {
* @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String informUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#informUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String informUser(TranslatableString message, final String translationContext);
+ // end::refguide[]
/**
* Warn the user about a situation with the specified message. The container
* should guarantee to display this warning to the user, and will typically
@@ -65,8 +72,10 @@ public interface MessageService {
* @see #raiseError(String)
* @see #informUser(String)
*/
+ // tag::refguide[]
void warnUser(String message);
+ // end::refguide[]
/**
* Warn the user about a situation with the specified message, translated (if possible) to user's locale.
*
@@ -80,13 +89,17 @@ public interface MessageService {
* @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String warnUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#warnUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String warnUser(TranslatableString message, final String translationContext);
+ // end::refguide[]
/**
* Notify the user of an application error with the specified message. Note
* this will probably be displayed in an alarming fashion, so is only
@@ -96,8 +109,10 @@ public interface MessageService {
* @see #warnUser(String)
* @see #informUser(String)
*/
+ // tag::refguide[]
void raiseError(String message);
+ // end::refguide[]
/**
* Notify the user of an application error with the specified message, translated (if possible) to user's locale.
*
@@ -111,11 +126,14 @@ public interface MessageService {
* @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String raiseError(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#raiseError(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String raiseError(TranslatableString message, final String translationContext);
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
index a696ab9..5a1f5a5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
@@ -18,37 +18,31 @@
*/
package org.apache.isis.applib.services.metamodel;
+// tag::refguide[]
public interface DomainMember extends Comparable<DomainMember> {
String getClassType();
String getClassName();
-
String getPackageName();
String getType();
String getMemberName();
-
String getNumParams();
boolean isContributed();
-
String getContributedBy();
boolean isMixedIn();
-
String getMixin();
String getHidden();
-
String getDisabled();
+ String getValidate();
String getChoices();
-
String getAutoComplete();
-
String getDefault();
-
- String getValidate();
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
index 0ba797f..2a0127d 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
@@ -20,8 +20,10 @@ package org.apache.isis.applib.services.metamodel;
import java.util.List;
+// tag::refguide[]
public interface DomainModel {
List<DomainMember> getDomainMembers();
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
index 6d820b0..dd2ebf5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
@@ -43,18 +43,23 @@ import lombok.val;
// tag::refguide[]
public interface MetaModelService {
+ // end::refguide[]
/**
* Provides a reverse lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
*/
+ // tag::refguide[]
Class<?> fromObjectType(final String objectType);
+ // end::refguide[]
/**
* Provides a lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
*/
+ // tag::refguide[]
String toObjectType(final Class<?> domainType);
void rebuild(final Class<?> domainType);
+ // end::refguide[]
/**
* Returns a list of representations of each of member of each domain class.
*
@@ -67,6 +72,7 @@ public interface MetaModelService {
* </p>
*
*/
+ // tag::refguide[]
DomainModel getDomainModel();
BeanSort sortOf(Class<?> domainType, Mode mode);
@@ -75,22 +81,28 @@ public interface MetaModelService {
CommandDtoProcessor commandDtoProcessorFor(String memberIdentifier);
-// end::refguide[]
-
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Mode {
+
+ // end::refguide-1[]
/**
* If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then throw an exception.
*/
+ // tag::refguide-1[]
STRICT,
+
+ // end::refguide-1[]
/**
* If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then return {@link Sort#UNKNOWN}.
*/
+ // tag::refguide-1[]
RELAXED
+
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide-2[]
+ // tag::refguide-2[]
class Config {
private static final int IGNORE_NOOP_FACETS = 1;
@@ -182,10 +194,9 @@ public interface MetaModelService {
}
}
-// end::refguide-2[]
-
-// tag::refguide[]
+ // end::refguide-2[]
+ // tag::refguide[]
MetamodelDto exportMetaModel(final Config config);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
index 12bcc47..5cfc02a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
@@ -42,16 +42,16 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
// tag::refguide[]
public interface AuditerService {
- boolean isEnabled(); // <1>
+ boolean isEnabled(); // <.>
void audit(
- final UUID interactionId, final int sequence, // <2>
+ final UUID interactionId, final int sequence, // <.>
final String targetClassName,
- final Bookmark target, // <3>
+ final Bookmark target, // <.>
final String memberIdentifier,
- final String propertyName, // <4>
- final String preValue, final String postValue, // <5>
- final String user, final Timestamp timestamp); // <6>
+ final String propertyName, // <.>
+ final String preValue, final String postValue, // <.>
+ final String user, final Timestamp timestamp); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
index adc9570..ebd7a23 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
@@ -59,10 +59,12 @@ public class AuditerServiceLogging implements AuditerService {
final String preValue, final String postValue,
final String user, final Timestamp timestamp) {
- String auditMessage =
- interactionId + "," + sequence + ": " +
- target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
- log.debug(auditMessage);
+ if(log.isDebugEnabled()) {
+ String auditMessage =
+ interactionId + "," + sequence + ": " +
+ target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
+ log.debug(auditMessage);
+ }
}
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
index 481db35..dc0e771 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
@@ -43,7 +43,7 @@ import lombok.val;
// tag::refguide[]
public class Bookmark implements Serializable {
-// end::refguide[]
+ // end::refguide[]
private static final long serialVersionUID = 2L;
protected static final String SEPARATOR = ":";
@@ -52,26 +52,28 @@ public class Bookmark implements Serializable {
* corresponds directly to the object's specification-id
* @see <code>RootOid</code>
*/
-// tag::refguide[]
+ // tag::refguide[]
@NonNull private final String objectType;
@NonNull private final String identifier;
-// end::refguide[]
+ // end::refguide[]
+
@Nullable private final String hintId;
-// tag::refguide[]
+ // tag::refguide[]
public static Bookmark of(String objectType, String identifier) {
return new Bookmark(objectType, identifier, /*hintId*/ null);
}
// ...
-// end::refguide[]
+ // end::refguide[]
/**
* Round-trip with {@link #toString()} representation.
*/
-// tag::refguide[]
+ // tag::refguide[]
public static Optional<Bookmark> parse(@Nullable String str) {
-// end::refguide[]
+ // end::refguide[]
+
if(str==null) {
return Optional.empty();
}
@@ -85,10 +87,10 @@ public class Bookmark implements Serializable {
}
return Optional.empty();
-// tag::refguide[]
+ // tag::refguide[]
// ...
}
-// end::refguide[]
+ // end::refguide[]
public OidDto toOidDto() {
val oidDto = new OidDto();
@@ -122,6 +124,6 @@ public class Bookmark implements Serializable {
return objectType + SEPARATOR + id;
}
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
index de4cfca..846273b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
import org.apache.isis.applib.annotation.Mixin;
import org.apache.isis.applib.annotation.SemanticsOf;
-// tag::refguide[]
@Mixin(method = "act")
public class BookmarkHolder_lookup {
@@ -42,11 +41,11 @@ public class BookmarkHolder_lookup {
@Action(
domainEvent = ActionDomainEvent.class,
semantics = SemanticsOf.SAFE
- )
+ )
@ActionLayout(
contributed = Contributed.AS_ACTION,
cssClassFa = "fa-bookmark"
- )
+ )
public Object act() {
return bookmarkService.lookup(bookmarkHolder);
}
@@ -54,4 +53,3 @@ public class BookmarkHolder_lookup {
@Inject private BookmarkService bookmarkService;
}
-// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
index 2565c2b..86b8528 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
import org.apache.isis.applib.annotation.Mixin;
import org.apache.isis.applib.annotation.SemanticsOf;
-// tag::refguide[]
@Mixin(method = "prop")
public class BookmarkHolder_object {
@@ -42,16 +41,14 @@ public class BookmarkHolder_object {
@Action(
semantics = SemanticsOf.SAFE,
domainEvent = BookmarkHolder_object.ActionDomainEvent.class
- )
+ )
@ActionLayout(
contributed = Contributed.AS_ASSOCIATION
- )
+ )
public Object prop() {
return bookmarkService.lookup(bookmarkHolder);
}
-
@Inject private BookmarkService bookmarkService;
}
-// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
index ada7068..a0ef829 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
@@ -20,6 +20,7 @@ package org.apache.isis.applib.services.bookmark;
import javax.annotation.Nullable;
+import org.apache.isis.applib.services.metamodel.MetaModelService;
import org.apache.isis.core.commons.internal.base._Casts;
import org.apache.isis.core.commons.internal.exceptions._Exceptions;
@@ -34,21 +35,31 @@ import lombok.val;
// tag::refguide[]
public interface BookmarkService {
-// end::refguide[]
+ // end::refguide[]
/**
- * Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
- * was created for.
+ * Returns the {@link Bookmark} for the given domain object.
+ *
* <p>
- * Note: Not every domain object is bookmark-able.
+ * <b>Note</b>: Not every domain object is bookmark-able: only entities, view models and services (NOT values or collections)
* </p>
- * @param domainObject
+ *
+ * @param domainObject - domain object (if any) to return a bookmark for
* @return optionally a {@link Bookmark} representing given {@code domainObject}
*/
-// tag::refguide[]
+ // tag::refguide[]
Bookmark bookmarkFor(@Nullable Object domainObject);
+ // end::refguide[]
+ /**
+ * As per {@link #bookmarkFor(Object)}, but requires that a non-null {@link Bookmark} is returned.
+ *
+ * @param domainObject - that can be bookmarked
+ * @return a (non-null) {@link Bookmark} for the provided domain object.
+ */
+ // tag::refguide[]
default Bookmark bookmarkForElseThrow(Object domainObject) {
-// end::refguide[]
+ // end::refguide[]
+
requires(domainObject, "domainObject");
val bookmark = bookmarkFor(domainObject);
if(bookmark!=null) {
@@ -56,21 +67,44 @@ public interface BookmarkService {
}
throw _Exceptions.illegalArgument(
"cannot create bookmark for type %s", domainObject.getClass().getName());
-// tag::refguide[]
+ // tag::refguide[]
// ...
}
+ // end::refguide[]
+ /**
+ * Utility method that creates a {@link Bookmark} from the constituent parts.
+ *
+ * @return - {@link Bookmark} for provided class and identifier
+ */
+ // tag::refguide[]
Bookmark bookmarkFor(Class<?> cls, String identifier);
+ // end::refguide[]
+ /**
+ * @see #lookup(Bookmark)
+ *
+ * @param bookmarkHolder - from which the {@link Bookmark} is obtained
+ * @return - corresponding domain object
+ */
+ // tag::refguide[]
Object lookup(BookmarkHolder bookmarkHolder);
+ // end::refguide[]
+ /**
+ * Reciprocal of {@link #bookmarkFor(Object)}
+ *
+ * @param bookmark - representing a domain object
+ * @return - the corresponding domain object
+ */
+ // tag::refguide[]
Object lookup(Bookmark bookmark);
-// end::refguide[]
+ // end::refguide[]
/**
* As {@link #lookup(Bookmark)}, but down-casting to the specified type.
*/
-// tag::refguide[]
+ // tag::refguide[]
default <T> T lookup(Bookmark bookmark, Class<T> cls) {
return cls.cast(lookup(bookmark));
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
index e21431b..d94ec32 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
@@ -23,6 +23,6 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface BookmarkUiService {
- void clear(); // <1>
+ void clear(); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
index 1230b7b..f030cb6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
@@ -105,9 +105,7 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* The date/time at which this command was created.
- *
*/
// tag::refguide[]
Timestamp getTimestamp(); // <.>
@@ -118,13 +116,13 @@ public interface Command extends HasUniqueId {
*
* <p>
* Will only be populated if a {@link BookmarkService} has been configured.
+ * </p>
*/
// tag::refguide[]
Bookmark getTarget(); // <.>
// end::refguide[]
/**
- *
* Holds a string representation of the invoked action, or the edited property, equivalent to
* {@link Identifier#toClassAndNameIdentityString()}.
*/
@@ -133,7 +131,6 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* A human-friendly description of the class of the target object.
*/
// tag::refguide[]
@@ -141,19 +138,13 @@ public interface Command extends HasUniqueId {
// end::refguide[]
/**
- *
* The human-friendly name of the action invoked/property edited on the target object.
- *
- * <p>
- * NB: in earlier versions, if the command represented an edit of a property, then it held the special value "{@value ACTION_IDENTIFIER_FOR_EDIT}". This is NO LONGER the case; it simply holds the member.
- * </p>
*/
// tag::refguide[]
String getTargetAction(); // <.>
// end::refguide[]
/**
- *
* A human-friendly description of the arguments with which the action was invoked.
*/
// tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
index 9716944..2f7b4d0 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
@@ -72,7 +72,7 @@ public class CommandContext {
@Getter
private Command command;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -85,7 +85,6 @@ public class CommandContext {
.map(Command::getExecutor);
}
-
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
index cfffa0a..917a4e5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
@@ -21,16 +21,25 @@ package org.apache.isis.applib.services.command;
// tag::refguide[]
public interface CommandExecutorService {
+ // end::refguide[]
+ // tag::refguide-2[]
enum SudoPolicy {
+
+ // end::refguide-2[]
/**
* For example, regular background commands.
*/
+ // tag::refguide-2[]
NO_SWITCH,
+
+ // end::refguide-2[]
/**
* For example, replayable commands.
*/
+ // tag::refguide-2[]
SWITCH,
}
+ // end::refguide-2[]
/**
* Executes the specified command.
@@ -39,7 +48,11 @@ public interface CommandExecutorService {
* @param commandWithDto
* @return - any exception raised by the command.
*/
- void executeCommand(SudoPolicy sudoPolicy, CommandWithDto commandWithDto);
+ // tag::refguide[]
+ void executeCommand(
+ SudoPolicy sudoPolicy, // <.>
+ CommandWithDto commandWithDto // <.>
+ );
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
index 8afa756..eb3abce 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
@@ -26,7 +26,7 @@ import org.apache.isis.applib.services.command.Command;
// tag::refguide[]
public interface CommandService {
-// end::refguide[]
+ // end::refguide[]
/**
* Simply instantiates the appropriate instance of the {@link Command}.
*
@@ -35,17 +35,17 @@ public interface CommandService {
* {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
* </p>
*/
-// tag::refguide[]
+ // tag::refguide[]
Command create(); // <.>
-// end::refguide[]
+ // end::refguide[]
/**
* Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
* of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
*/
-// tag::refguide[]
+ // tag::refguide[]
boolean persistIfPossible(Command command); // <.>
-// end::refguide[]
+ // end::refguide[]
/**
* "Complete" the command, typically meaning to indicate that the command is completed, and to
@@ -59,7 +59,7 @@ public interface CommandService {
* The framework will automatically have set the {@link Command#getCompletedAt()} property.
* </p>
*/
-// tag::refguide[]
+ // tag::refguide[]
void complete(final Command command); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
index bc71130..9627c0f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
@@ -26,10 +26,12 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface ConfigurationViewService {
+ // end::refguide[]
/**
* Returns all properties, each as an instance of {@link ConfigurationProperty} (a view model).
* Mask sensitive values if required.
*/
+ // tag::refguide[]
Set<ConfigurationProperty> allProperties();
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java b/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
index c95ad15..369349e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
@@ -30,15 +30,18 @@ import org.apache.isis.core.commons.internal.base._NullSafe;
// tag::refguide[]
public interface ContentMappingService {
+ // end::refguide[]
/**
* Typically for mapping from a domain object to a DTO.
*/
+ // tag::refguide[]
Object map(Object object, final List<MediaType> acceptableMediaTypes);
-// end::refguide[]
+ // end::refguide[]
/**
* Convenience utilities for implementations of {@link ContentMappingService}.
*/
+ // tag::refguide-2[]
public static class Util {
public static String determineDomainType(final List<MediaType> acceptableMediaTypes) {
@@ -64,7 +67,8 @@ public interface ContentMappingService {
return clazz.getName().equals(domainType);
}
}
+ // end::refguide-2[]
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java b/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
index be7f54d..e5960e7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
@@ -37,20 +37,16 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface EmailService extends Serializable {
- /**
- * Always called by the framework, and allows the implementation to read configuration properties and initialize itself
- */
@PostConstruct
public void init() ;
- /**
- * Main API to send email and optional attachments.
- */
boolean send(List<String> to, List<String> cc, List<String> bcc, String subject, String body, DataSource... attachments);
+ // end::refguide[]
/**
* Whether this service has been configured and thus available for use.
*/
+ // tag::refguide[]
boolean isConfigured();
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java b/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
index 0d55843..dca850f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
@@ -34,10 +34,13 @@ import java.io.Serializable;
// tag::refguide[]
public interface Ticket extends Serializable {
+ // end::refguide[]
+ // tag::refguide-2[]
enum StackTracePolicy {
SHOW,
HIDE
}
+ // end::refguide-2[]
/**
* A unique identifier that the end-user can use to track any follow-up from this error.
@@ -47,8 +50,10 @@ public interface Ticket extends Serializable {
* which case the {@link #getReference() reference} would be the JIRA issue number <tt>XXX-1234</tt>.
* </p>
*/
+ // tag::refguide[]
String getReference();
+ // end::refguide[]
/**
* Message to display to the user.
*
@@ -56,8 +61,10 @@ public interface Ticket extends Serializable {
* Typically this message should be short, one line long.
* </p>
*/
+ // tag::refguide[]
String getUserMessage();
+ // end::refguide[]
/**
* Optional additional details to show to the end-user.
*
@@ -66,8 +73,10 @@ public interface Ticket extends Serializable {
* details on contacting the help desk if the issue is severe and requires immediate attention.
* </p>
*/
+ // tag::refguide[]
String getDetails();
+ // end::refguide[]
/**
* Whether the stack trace for the exception should be displayed or be hidden.
*
@@ -76,11 +85,14 @@ public interface Ticket extends Serializable {
* the support team, meaning there's no need to expose this info to the end-user.
* </p>
*/
+ // tag::refguide[]
StackTracePolicy getStackTracePolicy();
+ // end::refguide[]
/**
* Returns a Html representation of this ticket.
*/
+ // tag::refguide[]
String getMarkup();
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
index c5ca151..8c75c23 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
@@ -61,63 +61,86 @@ import lombok.val;
// tag::refguide[]
public interface ExceptionRecognizer {
+ // end::refguide[]
/**
* (Attempt to) recognize the exception and return a user-friendly
- * message to render instead.
+ * message to render instead.
*
- * @return optionally a
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
- * that describes both the
- * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
- * and reason that will be included with the user-friendly message.
+ * @return optionally a
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
+ * that describes both the
+ * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
+ * and reason that will be included with the user-friendly message.
*/
+ // tag::refguide[]
Optional<Recognition> recognize(Throwable ex);
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
@RequiredArgsConstructor
enum Category {
+
+ // end::refguide-1[]
/**
* A violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
*/
+ // tag::refguide-1[]
CONSTRAINT_VIOLATION("violation of some declarative constraint"),
+
+ // end::refguide-1[]
/**
* The object to be acted upon cannot be found (404)
*/
+ // tag::refguide-1[]
NOT_FOUND("object not found"),
+
+ // end::refguide-1[]
/**
* A concurrency exception, in other words some other user has changed this object.
*/
+ // tag::refguide-1[]
CONCURRENCY("concurrent modification"),
+
+ // end::refguide-1[]
/**
* Recognized, but for some other reason... 40x error
*/
+ // tag::refguide-1[]
CLIENT_ERROR("client side error"),
+
+ // end::refguide-1[]
/**
* 50x error
*/
+ // tag::refguide-1[]
SERVER_ERROR("server side error"),
+
+ // end::refguide-1[]
/**
* Recognized, but uncategorized (typically: a recognizer of the original ExceptionRecognizer API).
*/
+ // tag::refguide-1[]
OTHER("other")
;
-
+
@Getter
private final String friendlyName;
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide-2[]
+ // tag::refguide-2[]
@Value
class Recognition {
+ // end::refguide-2[]
/**
* @return optionally a recognition of the specified type, based on a whether given reason is non-null
*/
+ // tag::refguide-2[]
public static Optional<Recognition> of(
@Nullable final Category category,
@Nullable final String reason) {
+ // end::refguide-2[]
if(reason==null) {
return Optional.empty();
@@ -125,27 +148,34 @@ public interface ExceptionRecognizer {
val nonNullCategory = category!=null? category: Category.OTHER;
return Optional.of(new Recognition(nonNullCategory, reason));
+ // tag::refguide-2[]
+ // ...
}
@NonNull private final Category category;
@NonNull private final String reason;
public String toMessage(@Nullable TranslationService translationService) {
-
+ // end::refguide-2[]
+
val categoryLiteral = translationService!=null
? translationService.translate(
ExceptionRecognizer.Category.class.getName(), getCategory().getFriendlyName())
: getCategory().getFriendlyName();
-
+
val reasonLiteral = translationService!=null
? translationService.translate(
ExceptionRecognizer.Recognition.class.getName(), getReason())
: getReason();
-
+
return String.format("[%s]: %s", categoryLiteral, reasonLiteral);
+ // tag::refguide-2[]
+ // ...
}
+ // end::refguide-2[]
}
-// end::refguide-2[]
-// tag::refguide[]
+ // end::refguide-2[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
index 64e0edd..2c8043b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
@@ -31,31 +31,38 @@ import org.apache.isis.core.commons.collections.Can;
// tag::refguide[]
public interface ExceptionRecognizerService {
+ // end::refguide[]
/**
- *
- * @return all ExceptionRecognizer implementations as discovered by the IoC container,
- * honoring order of precedence.
+ *
+ * @return all ExceptionRecognizer implementations as discovered by the IoC container,
+ * honoring order of precedence.
*/
+ // tag::refguide[]
Can<ExceptionRecognizer> getExceptionRecognizers();
+ // end::refguide[]
/**
* Takes into consideration ExceptionRecognizers as given by {@link #getExceptionRecognizers()}.
*
- * @param ex
- * @return optionally a recognition object, that describes both the category and reason,
- * that will be included with the user-friendly message.
+ * @param ex - exception to be recognized
+ * @return optionally a recognition object, that describes both the category and reason,
+ * that will be included with the user-friendly message.
*/
+ // tag::refguide[]
default Optional<Recognition> recognize(Exception ex) {
return recognizeFromSelected(getExceptionRecognizers(), ex);
}
+ // end::refguide[]
/**
* Takes into consideration ExceptionRecognizers as given by {@code recognizers}.
- * @param recognizers
- * @param ex
- * @return optionally a recognition object, that describes both the category and reason,
- * that will be included with the user-friendly message.
+ *
+ * @param recognizers - one or more recognizers to attempt to recognize the exceptoin
+ * @param ex - the exception to be recognized
+ * @return optionally a recognition object, that describes both the category and reason,
+ * that will be included with the user-friendly message.
*/
+ // tag::refguide[]
Optional<Recognition> recognizeFromSelected(Can<ExceptionRecognizer> recognizers, Exception ex);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
index 58e27e4..1e70cbc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
@@ -33,6 +33,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
// tag::refguide[]
public interface TranslatableException {
+ // end::refguide[]
/**
* In the spirit of {@link Exception#getLocalizedMessage()}, but using {@link org.apache.isis.applib.services.i18n.TranslatableString} instead.
*
@@ -43,12 +44,15 @@ public interface TranslatableException {
* accept a {@link org.apache.isis.applib.services.i18n.TranslatableString}, but can be left as null for any existing code.
* </p>
*/
+ // tag::refguide[]
TranslatableString getTranslatableMessage();
+ // end::refguide[]
/**
* The context to use when translating the {@link #getTranslatableMessage() translatable message},
* as ultimately passed through to {@link org.apache.isis.applib.services.i18n.TranslationService#translate(String, String)}.
*/
+ // tag::refguide[]
String getTranslationContext();
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
index b03a26e..e09fdf6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
@@ -23,17 +23,19 @@ import java.util.NoSuchElementException;
import javax.annotation.Nullable;
+import org.apache.isis.applib.services.repository.RepositoryService;
import org.apache.isis.core.commons.exceptions.IsisException;
// tag::refguide[]
public interface FactoryService {
+ // end::refguide[]
/**
* General purpose factory method, to automatically get or create an instance of
* {@code requiredType}.
*
* <p>
- * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
+ * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
* based on the type's meta-data.
* </p>
*
@@ -47,40 +49,48 @@ public interface FactoryService {
* @since 2.0
*
*/
+ // tag::refguide[]
<T> T getOrCreate(Class<T> requiredType);
+ // end::refguide[]
/**
- * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
- * with injection points resolved
+ * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
+ * with injection points resolved
* and any life-cycle callback processed.
- *
+ *
* @param <T>
* @param requiredType - only applicable to IoC container managed types
* @return (non-null), an instance of {@code requiredType}, if available and unique
* (i.e. not multiple candidates found with none marked as primary)
- *
+ *
* @throws NoSuchElementException if result is empty
* @throws IsisException if instance creation failed
- *
+ *
* @apiNote does not force the requiredType to be added to the meta-model
* @since 2.0
*/
+ // tag::refguide[]
<T> T get(Class<T> requiredType);
+ // end::refguide[]
/**
* Creates a new detached entity instance, with injection points resolved
* and defaults applied.
+ *
* @param <T>
* @param domainClass - only applicable to entity types
* @return
- * @throws IllegalArgumentException if domainClass is not an entity type
+ * @throws IllegalArgumentException if domainClass is not an entity type
* @apiNote forces the domainClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T detachedEntity(Class<T> domainClass);
+ // end::refguide[]
/**
* Creates a new Mixin instance, with injection points resolved.
+ *
* @param <T>
* @param mixinClass
* @param mixedIn
@@ -88,44 +98,52 @@ public interface FactoryService {
* @throws IllegalArgumentException if mixinClass is not a mixin type
* @apiNote forces the mixinClass to be added to the meta-model if not already
*/
+ // tag::refguide[]
<T> T mixin(Class<T> mixinClass, Object mixedIn);
+ // end::refguide[]
/**
- * Creates a new ViewModel instance, with injection points resolved,
- * and initialized according to the given {@code mementoStr}
+ * Creates a new ViewModel instance, with injection points resolved,
+ * and initialized according to the given {@code mementoStr}
+ *
* @param viewModelClass
* @param mementoStr - ignored if {@code null}
* @throws IllegalArgumentException if viewModelClass is not a viewmodel type
* @apiNote forces the viewModelClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T viewModel(Class<T> viewModelClass, @Nullable String mementoStr);
+ // end::refguide[]
/**
- * Creates a new ViewModel instance,
+ * Creates a new ViewModel instance,
* with injection points resolved
- * and defaults applied.
+ * and defaults applied.
* @param viewModelClass
* @throws IllegalArgumentException if viewModelClass is not a viewmodel type
* @apiNote forces the viewModelClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
default <T> T viewModel(Class<T> viewModelClass) {
return viewModel(viewModelClass, /*mementoStr*/null);
}
+ // end::refguide[]
/**
- * Creates a new instance of the specified class,
+ * Creates a new instance of the specified class,
* with injection points resolved
* and defaults applied.
* @param domainClass - not applicable to IoC container managed types
- * @throws IllegalArgumentException if domainClass is an IoC container managed type,
+ * @throws IllegalArgumentException if domainClass is an IoC container managed type,
* or not recognized by the meta-model
* @apiNote forces the domainClass to be added to the meta-model if not already
* @since 2.0
*/
+ // tag::refguide[]
<T> T create(Class<T> domainClass);
-// end::refguide[]
+ // end::refguide[]
// -- DEPRECATIONS
@@ -156,8 +174,8 @@ public interface FactoryService {
* alternatively just <i>new()</i> up the object rather than call this
* method.
* </p>
- * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
- * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
+ * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
+ * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
* if applicable
*/
@Deprecated
@@ -165,6 +183,6 @@ public interface FactoryService {
return getOrCreate(domainClass);
}
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
index 7828441..202eb65 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
@@ -24,31 +24,41 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridLoaderService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* To support metamodel invalidation/rebuilding of spec.
*/
+ // tag::refguide[]
void remove(Class<?> domainClass);
+ // end::refguide[]
/**
* Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
*/
+ // tag::refguide[]
boolean existsFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass, String layout);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
index bdfa20a..f9db3c5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
@@ -29,32 +29,43 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* To support metamodel invalidation/rebuilding of spec.
*/
+ // tag::refguide[]
void remove(Class<?> domainClass);
+ // end::refguide[]
/**
* Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
*/
+ // tag::refguide[]
boolean existsFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>layout.xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(final Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a default grid; eg where none can be loaded using {@link #load(Class)}.
*/
+ // tag::refguide[]
Grid defaultGridFor(Class<?> domainClass);
+ // end::refguide[]
/**
* Returns a normalized grid for the domain class obtained previously using {@link #load(Class)}.
*
@@ -69,8 +80,10 @@ public interface GridService {
* <code>layout.xml</code> file takes precedence over any annotations.
* </p>
*/
+ // tag::refguide[]
Grid normalize(final Grid grid);
+ // end::refguide[]
/**
* Modifies the provided {@link Grid} with additional metadata, broadly speaking corresponding to the
* {@link DomainObjectLayout}, {@link ActionLayout}, {@link PropertyLayout} and {@link CollectionLayout}.
@@ -81,8 +94,10 @@ public interface GridService {
* to be required in the domain class itself.
* </p>
*/
+ // tag::refguide[]
Grid complete(Grid grid);
+ // end::refguide[]
/**
* Modifies the provided {@link Grid}, removing all metadata except the basic grid structure.
*
@@ -95,12 +110,15 @@ public interface GridService {
* @param grid
* @return
*/
+ // tag::refguide[]
Grid minimal(Grid grid);
+ // end::refguide[]
/**
* Returns a new instance of a {@link Grid} for the specified domain class, eg from a
* <code>[domainClass].layout.[layout].xml</code> file, else <code>null</code>.
*/
+ // tag::refguide[]
Grid load(Class<?> domainClass, String layout);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
index bdeab5d..5a2c289 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
@@ -27,9 +27,11 @@ import org.apache.isis.applib.layout.grid.Grid;
// tag::refguide[]
public interface GridSystemService<G extends Grid> {
+ // end::refguide[]
/**
* Which grid (implementation) is defined by this service.
*/
+ // tag::refguide[]
Class<G> gridImplementation();
String tns();
@@ -38,10 +40,12 @@ public interface GridSystemService<G extends Grid> {
G defaultGrid(Class<?> domainClass);
+ // end::refguide[]
/**
* Validate the grid, derive any missing object members, and overwrite any facets in the metamodel based on the
* layout.
*/
+ // tag::refguide[]
void normalize(G grid, Class<?> domainClass);
void complete(G grid, Class<?> domainClass);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java b/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
index 82c7dda..c908630 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
@@ -21,6 +21,7 @@ package org.apache.isis.applib.services.health;
import lombok.AllArgsConstructor;
import lombok.Getter;
+// tag::refguide[]
@AllArgsConstructor
public class Health {
@@ -41,3 +42,4 @@ public class Health {
public boolean getResult() { return message == null; }
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java b/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
index da2d21e..8572827 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
@@ -26,13 +26,13 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
// tag::refguide[]
public interface HintStore {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
interface HintIdProvider {
String hintId();
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
+ // tag::refguide[]
String get(final Bookmark bookmark, String hintKey);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
index 263ae0e..a4a7f6b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
@@ -22,6 +22,7 @@ import org.apache.isis.applib.annotation.HomePage;
/**
* Returns a view model annotated with {@link HomePage}.
+ *
* @since 2.0
*/
// tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
similarity index 77%
copy from api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
copy to api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
index 0ba797f..2bb38af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
@@ -16,12 +16,9 @@
* specific language governing permissions and limitations
* under the License.
*/
-package org.apache.isis.applib.services.metamodel;
-import java.util.List;
-
-public interface DomainModel {
-
- List<DomainMember> getDomainMembers();
-
-}
+/**
+ * The {@link org.apache.isis.applib.services.homepage.HomePageResolverService} returns the view model, if any
+ * annotated with {@link org.apache.isis.applib.annotation.HomePage}.
+ */
+package org.apache.isis.applib.services.homepage;
\ No newline at end of file
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
index 8f8f1f9..30de466 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.Programmatic;
import org.apache.isis.applib.annotation.Value;
import org.apache.isis.core.commons.internal.collections._Lists;
+// tag::refguide[]
@Value
public final class TranslatableString {
+ // end::refguide[]
// -- tr, trn (factory methods); constructor
/**
@@ -39,15 +41,22 @@ public final class TranslatableString {
* @param pattern - pattern for all (singular and plural) form, with <code>${xxx}</code> placeholders
* @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
*/
+ // tag::refguide[]
public static TranslatableString tr(
final String pattern,
final Object... paramArgs) {
+ // end::refguide[]
+
if(pattern == null) {
return null;
}
return new TranslatableString(Type.TR, pattern, null, 1, asMap(paramArgs));
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* A translatable string with different patterns for singular and plural forms, selected automatically by the number
*
@@ -56,14 +65,20 @@ public final class TranslatableString {
* @param number - whether to use singular or plural form when rendering
* @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
*/
+ // tag::refguide[]
public static TranslatableString trn(
final String singularPattern,
final String pluralPattern,
final int number,
final Object... paramArgs) {
+
return new TranslatableString(Type.TRN, singularPattern, pluralPattern, number, asMap(paramArgs));
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* Converts a list of objects [a, 1, b, 2] into a map {a -> 1; b -> 2}
*/
@@ -181,8 +196,9 @@ public final class TranslatableString {
* @param context
* @return
*/
- @Programmatic
+ // tag::refguide[]
public String translate(final TranslationService translationService, final String context) {
+
final String translatedText =
!isPluralForm()
? translationService.translate(context, getSingularText())
@@ -190,6 +206,7 @@ public final class TranslatableString {
return translated(translatedText);
}
+ // end::refguide[]
/**
* The text to be translated; depends on whether {@link #isPluralForm()} and whether to be translated.
*
@@ -203,10 +220,11 @@ public final class TranslatableString {
* {@link Exception#getMessage() message} when only a translatable message has been provided.
* </p>
*/
- @Programmatic
+ // tag::refguide[]
public String getPattern() {
return !isPluralForm() || number == 1 ? getSingularText() : getPluralText();
}
+ // end::refguide[]
String translated(final String translatedText) {
return format(translatedText, argumentsByParameterName);
@@ -269,6 +287,6 @@ public final class TranslatableString {
return type.toString(this);
}
-
-
+ // tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
index 17e791e..5f55e2f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
@@ -24,6 +24,7 @@ import java.util.function.Predicate;
// tag::refguide[]
public interface TranslationService {
+ // end::refguide[]
/**
* Return a translation of the text, in the locale of the "current user".
*
@@ -35,8 +36,10 @@ public interface TranslationService {
* @param text
* @return
*/
+ // tag::refguide[]
String translate(final String context, final String text);
+ // end::refguide[]
/**
* Return a translation of either the singular or the plural text, dependent on the <tt>num</tt> parameter,
* in the locale of the "current user".
@@ -51,23 +54,48 @@ public interface TranslationService {
* @param num - whether to return the translation of the singular (if =1) or of the plural (if != 1)
* @return
*/
+ // tag::refguide[]
String translate(final String context, final String singularText, final String pluralText, int num);
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Mode {
- DISABLED(configValue->configValue != null &&
- ("disable".equalsIgnoreCase(configValue) ||
- "disabled".equalsIgnoreCase(configValue))),
+
+ DISABLED (
+ // end::refguide-1[]
+ configValue->
+ ("disable".equalsIgnoreCase(configValue) ||
+ "disabled".equalsIgnoreCase(configValue))
+ // tag::refguide-1[]
+ // ...
+ ),
// synonym, needs to be defined, such that config beans (since 2.0) do work
- DISABLE(configValue->false),
+ DISABLE(
+ // end::refguide-1[]
+ configValue->false
+ // tag::refguide-1[]
+ // ...
+ ),
+
+ READ(
+ // end::refguide-1[]
+ configValue->
+ ("read".equalsIgnoreCase(configValue) ||
+ "reader".equalsIgnoreCase(configValue))
+ // tag::refguide-1[]
+ // ...
+ ),
- READ(configValue->configValue != null &&
- ("read".equalsIgnoreCase(configValue) ||
- "reader".equalsIgnoreCase(configValue))),
- // default
- WRITE(configValue->!READ.matches(configValue) && !DISABLED.matches(configValue));
+ WRITE(
+ // end::refguide-1[]
+ configValue ->
+ !READ.matches(configValue) &&
+ !DISABLED.matches(configValue)
+ // tag::refguide-1[]
+ // ...
+ );
+ // end::refguide-1[]
// -- handle values from configuration
@@ -90,9 +118,10 @@ public interface TranslationService {
public boolean isDisabled() {
return this == DISABLED || this == DISABLE;
}
+
+ // tag::refguide-1[]
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
/**
* Whether this implementation is operating in read or in write mode.
@@ -112,6 +141,8 @@ public interface TranslationService {
* such that all pathways are exercised..
* </p>
*/
+ // tag::refguide[]
Mode getMode();
+
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
index 65a2112..c65f26f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
@@ -84,11 +84,12 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class Interaction implements HasUniqueId {
-
@Getter @Setter
private UUID uniqueId;
+ // end::refguide[]
private final List<Execution<?,?>> executionGraphs = _Lists.newArrayList();
+
/**
* Returns a (list of) {@link Execution}s in the order that they were pushed. Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
*
@@ -105,23 +106,33 @@ public class Interaction implements HasUniqueId {
* {@link #execute(MemberExecutor, ActionInvocation, ClockService, MetricsService)} for us, to ensure that the
* graph is populated, but then delegate to the PublisherService immediately at the end... ie {@link org.apache.isis.schema.ixn.v2.InteractionDto}s are published as we go, not all in a batch at the end.
*/
+ // tag::refguide[]
public List<Execution<?,?>> getExecutions() {
+ // end::refguide[]
+
return Collections.unmodifiableList(executionGraphs);
+
+ // tag::refguide[]
+ // ...
}
+ // end::refguide[]
/**
* The current (most recently pushed) {@link Execution}.
*/
+ // tag::refguide[]
@Getter
private Execution<?,?> currentExecution;
+ // end::refguide[]
/**
* The execution that preceded the current one.
*/
+ // tag::refguide[]
@Getter
private Execution<?,?> priorExecution;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*
@@ -270,51 +281,69 @@ public class Interaction implements HasUniqueId {
}
-// tag::refguide-1[]
/**
* Enumerates the different reasons why multiple occurrences of a certain type might occur within a single
* (top-level) interaction.
*/
+ // tag::refguide-1[]
public enum Sequence {
+ // end::refguide-1[]
/**
* Each interaction is either an action invocation or a property edit. There could be multiple of these,
* typically as the result of a nested calls using the {@link WrapperFactory}. Another reason is
* support for bulk action invocations within a single transaction.
*/
+ // tag::refguide-1[]
INTERACTION,
+
+ // end::refguide-1[]
/**
* For objects: multiple such could be dirtied and thus published as separate events. For actions
* invocations/property edits : multiple sub-invocations could occur if sub-invocations are made through the
* {@link WrapperFactory}.
*/
+ // tag::refguide-1[]
PUBLISHED_EVENT,
+
+ // end::refguide-1[]
/**
* There may be multiple transactions within a given interaction.
*/
+ // tag::refguide-1[]
TRANSACTION,
;
+ // end::refguide-1[]
public String id() {
return Interaction.Sequence.class.getName() + "#" + name();
}
+ // tag::refguide-1[]
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide[]
+ // tag::refguide[]
private final Map<String, LongAdder> maxBySequence = _Maps.newHashMap();
+ // end::refguide[]
/**
- * Generates numbers in a named sequence. The name of the sequence can be arbitrary, though note that the
- * framework also uses this capability to generate sequence numbers corresponding to the sequences enumerated by
- * the {@link Sequence} enum.
+ * Generates numbers in a named sequence.
+ *
+ * The name of the sequence can be arbitrary, though note that the framework also uses this capability to
+ * generate sequence numbers corresponding to the sequences enumerated by the {@link Sequence} enum.
*/
+ // tag::refguide[]
public int next(final String sequenceId) {
+ // end::refguide[]
+
final LongAdder adder = maxBySequence.computeIfAbsent(sequenceId, this::newAdder);
adder.increment();
return adder.intValue();
+
+ // tag::refguide[]
+ // ...
}
-// end::refguide[]
+ // end::refguide[]
private LongAdder newAdder(String ignore) {
final LongAdder adder = new LongAdder();
@@ -322,38 +351,46 @@ public class Interaction implements HasUniqueId {
return adder;
}
-// tag::refguide-2[]
/**
* Represents an action invocation/property edit as a node in a call-stack execution graph, with sub-interactions
* being made by way of the {@link WrapperFactory}).
*/
+ // tag::refguide-2[]
public static abstract class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
- // -- fields, constructor
-
@Getter
private final Interaction interaction;
@Getter
private final InteractionType interactionType;
@Getter
private final String memberIdentifier;
+
+ // end::refguide-2[]
/**
* The target of the action invocation. If this interaction is for a mixin action, then will be the
* mixed-in target (not the transient mixin itself).
*/
+ // tag::refguide-2[]
@Getter
private final Object target;
+
+ // end::refguide-2[]
/**
* A human-friendly description of the class of the target object.
*/
+ // tag::refguide-2[]
@Getter
private final String targetClass;
+
+ // end::refguide-2[]
/**
* The human-friendly name of the action invoked/property edited on the target object.
*/
+ // tag::refguide-2[]
@Getter
private final String targetMember;
+ // end::refguide-2[]
protected Execution(
final Interaction interaction,
final InteractionType interactionType,
@@ -377,9 +414,11 @@ public class Interaction implements HasUniqueId {
/**
* The action/property that invoked this action/property edit (if any).
*/
+ // tag::refguide-2[]
@Getter
private Execution<?,?> parent;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -393,13 +432,17 @@ public class Interaction implements HasUniqueId {
/**
* The actions/property edits made in turn via the {@link WrapperFactory}.
*/
+ // tag::refguide-2[]
public List<Execution<?,?>> getChildren() {
- return Collections.unmodifiableList(children);
- }
+ // end::refguide-2[]
+ return Collections.unmodifiableList(children);
- // -- event
+ // tag::refguide-2[]
+ // ...
+ }
+ // end::refguide-2[]
/**
* The domain event fired on the {@link EventBusService event bus} representing the execution of
* this action invocation/property edit.
@@ -410,9 +453,11 @@ public class Interaction implements HasUniqueId {
* {@link AbstractDomainEvent.Phase#EXECUTING executing} phase.
* </p>
*/
+ // tag::refguide-2[]
@Getter
private E event;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -420,29 +465,35 @@ public class Interaction implements HasUniqueId {
this.event = event;
}
-
- // -- startedAt, completedAt
-
/**
* The date/time at which this execution started.
*/
+ // tag::refguide-2[]
@Getter
private Timestamp startedAt;
+ // end::refguide-2[]
/**
* The date/time at which this execution completed.
*/
+ // tag::refguide-2[]
@Getter
private Timestamp completedAt;
public Timestamp start(
final ClockService clockService,
final MetricsService metricsService) {
+ // end::refguide-2[]
+
val startedAt = clockService.nowAsJavaSqlTimestamp();
syncMetrics(When.BEFORE, startedAt, metricsService);
return startedAt;
+
+ // tag::refguide-2[]
+ // ...
}
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -452,7 +503,6 @@ public class Interaction implements HasUniqueId {
syncMetrics(When.AFTER, completedAt, metricsService);
}
-
/**
* The object returned by the action invocation/property edit.
*
@@ -464,9 +514,11 @@ public class Interaction implements HasUniqueId {
* For <tt>void</tt> methods and for actions returning collections, the value
* will be <tt>null</tt>.
*/
+ // tag::refguide-2[]
@Getter
private Object returned;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -474,9 +526,11 @@ public class Interaction implements HasUniqueId {
this.returned = returned;
}
+ // tag::refguide-2[]
@Getter
private Exception threw;
+ // end::refguide-2[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
@@ -496,10 +550,11 @@ public class Interaction implements HasUniqueId {
* {@link Execution#getReturned()}) will (obviously) still be null.
* </p>
*/
+ // tag::refguide-2[]
@Getter
private T dto;
-
+ // end::refguide-2[]
/**
* <b>NOT API</b>: Set by framework (implementation of {@link MemberExecutor})
*/
@@ -508,12 +563,13 @@ public class Interaction implements HasUniqueId {
}
-
// -- helpers (syncMetrics)
-// tag::refguide-2a[]
+ // tag::refguide-2a[]
enum When {
BEFORE {
+ // end::refguide-2a[]
+
@Override
void syncMetrics(
final Execution<?, ?> execution,
@@ -533,8 +589,12 @@ public class Interaction implements HasUniqueId {
numberObjectsDirtiedFor(objectCountsDto).setBefore(numberObjectsDirtied);
}
+ // tag::refguide-2a[]
+ // ....
},
AFTER {
+ // end::refguide-2a[]
+
@Override void syncMetrics(
final Execution<?, ?> execution,
final Timestamp timestamp,
@@ -553,7 +613,10 @@ public class Interaction implements HasUniqueId {
numberObjectsDirtiedFor(objectCountsDto).setAfter(numberObjectsDirtied);
}
+ // tag::refguide-2a[]
+ // ....
};
+ // end::refguide-2a[]
// -- helpers
@@ -582,7 +645,10 @@ public class Interaction implements HasUniqueId {
final Timestamp timestamp,
final int numberObjectsLoaded,
final int numberObjectsDirtied);
+ // tag::refguide-2a[]
}
+ // end::refguide-2a[]
+
private void syncMetrics(
final When when,
final Timestamp timestamp,
@@ -593,16 +659,17 @@ public class Interaction implements HasUniqueId {
when.syncMetrics(this, timestamp, numberObjectsLoaded, numberObjectsDirtied);
}
-// end::refguide-2a[]
+ // tag::refguide-2[]
}
-// end::refguide-2[]
+ // end::refguide-2[]
-// tag::refguide-3[]
+ // tag::refguide-3[]
public static class ActionInvocation extends Execution<ActionInvocationDto, ActionDomainEvent<?>> {
@Getter
private final List<Object> args;
+ // end::refguide-3[]
public ActionInvocation(
final Interaction interaction,
@@ -614,14 +681,17 @@ public class Interaction implements HasUniqueId {
super(interaction, InteractionType.ACTION_INVOCATION, memberId, target, targetMember, targetClass);
this.args = args;
}
+ // tag::refguide-3[]
+ // ...
}
-// end::refguide-3[]
+ // end::refguide-3[]
-// tag::refguide-4[]
+ // tag::refguide-4[]
public static class PropertyEdit extends Execution<PropertyEditDto, PropertyDomainEvent<?,?>> {
@Getter
private final Object newValue;
+ // end::refguide-4[]
public PropertyEdit(
final Interaction interaction,
@@ -633,9 +703,12 @@ public class Interaction implements HasUniqueId {
super(interaction, InteractionType.PROPERTY_EDIT, memberId, target, targetMember, targetClass);
this.newValue = newValue;
}
+
+ // tag::refguide-4[]
+ // ...
}
-// end::refguide-4[]
+ // end::refguide-4[]
-// tag::refguide[]
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
index a3899aa..b51c596 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
@@ -51,7 +51,7 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class InteractionContext {
-// end::refguide[]
+ // end::refguide[]
public InteractionContext() {
log.debug("init");
}
@@ -66,13 +66,13 @@ public class InteractionContext {
log.debug("preDestroy");
}
-// tag::refguide[]
/**
* The currently active {@link Interaction} for this thread.
*/
+ // tag::refguide[]
@Getter
private Interaction interaction;
-// end::refguide[]
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
@@ -80,6 +80,7 @@ public class InteractionContext {
public void setInteraction(final Interaction interaction) {
this.interaction = interaction;
}
-// tag::refguide[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java b/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
index ea7e137..dcfee4a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
@@ -39,6 +39,8 @@ public interface ServiceInjector {
<T> T injectServicesInto(final T domainObject, Consumer<InjectionPoint> onNotResolvable);
default <T> T injectServicesInto(final T domainObject) {
+ // end::refguide[]
+
return injectServicesInto(domainObject, injectionPoint->{
val injectionPointName = injectionPoint.toString();
@@ -51,6 +53,9 @@ public interface ServiceInjector {
throw new NoSuchElementException(msg);
});
+ // tag::refguide[]
+ // ...
}
+
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
index ad86f6a..61bafdc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
@@ -47,14 +47,18 @@ public interface JaxbService {
Object fromXml(JAXBContext jaxbContext, String xml, Map<String,Object> unmarshallerProperties);
+ // end::refguide[]
/**
* As {@link #fromXml(JAXBContext, String)}, but downcast to a specific type.
*/
+ // tag::refguide[]
<T> T fromXml(Class<T> domainClass, String xml);
+ // end::refguide[]
/**
* As {@link #fromXml(JAXBContext, String, Map)}, but downcast to a specific type.
*/
+ // tag::refguide[]
<T> T fromXml(Class<T> domainClass, String xml, Map<String,Object> unmarshallerProperties);
String toXml(final Object domainObject);
@@ -75,10 +79,11 @@ public interface JaxbService {
* <a href="http://isis.apache.org/schema">downloaded</a> from the Isis website.
* </p>
*/
+ // tag::refguide[]
enum IsisSchemas {
INCLUDE,
IGNORE;
-// end::refguide[]
+ // end::refguide[]
/**
* Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
@@ -90,12 +95,12 @@ public interface JaxbService {
return namespaceUri.matches(".*isis\\.apache\\.org.*");
}
}
-// tag::refguide[]
+ // tag::refguide[]
}
Map<String, String> toXsd(final Object domainObject, final IsisSchemas isisSchemas);
-// end::refguide[]
+ // end::refguide[]
class Simple implements JaxbService {
@Override
@@ -245,6 +250,7 @@ public interface JaxbService {
}
}
}
-// tag::refguide[]
+
+ // tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
index 598cc6c..a0fb471 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
@@ -25,15 +25,17 @@ import org.apache.isis.applib.services.menu.MenuBarsService;
// tag::refguide[]
public interface LayoutService {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+
/**
* Mode of operation when downloading a layout file (while prototyping). It affects the way the file's
* content is assembled. Once a layout file is in place, its layout data takes precedence over any
* conflicting layout data from annotations.
*/
+ // tag::refguide-1[]
enum Style {
+ // end::refguide-1[]
/**
* The current layout for the domain class.
* <p>
@@ -43,8 +45,10 @@ public interface LayoutService {
* {@link org.apache.isis.applib.services.grid.GridService#defaultGridFor(Class) default grid},
* also {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
*/
+ // tag::refguide-1[]
CURRENT,
+ // end::refguide-1[]
/**
* As per {@link #NORMALIZED}, but also with all (non-null) facets for all
* properties/collections/actions also included included in the grid.
@@ -56,13 +60,15 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>serialized as XML</b></li>
* </ul>
*/
+ // tag::refguide-1[]
COMPLETE,
+ // end::refguide-1[]
/**
* Default, whereby missing properties/collections/actions are added to regions,
* and unused/empty regions are removed/trimmed.
* <p>
- * It should be possible to remove any {@link MemberOrder} and {@link MemberGroupLayout} annotation but
+ * It should be possible to remove any {@link MemberOrder} annotation but
* any property/collection/action layout annotations would need to be retained.
* <ul>
* <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
@@ -70,8 +76,10 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
* </ul>
*/
+ // tag::refguide-1[]
NORMALIZED,
+ // end::refguide-1[]
/**
* As per {@link #NORMALIZED}, but with no properties/collections/actions.
* <p>
@@ -83,25 +91,31 @@ public interface LayoutService {
* <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
* </ul>
*/
+ // tag::refguide-1[]
MINIMAL
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide[]
+ // end::refguide[]
/**
* Obtains the serialized XML form of the layout (grid) for the specified domain class.
*/
+ // tag::refguide[]
String toXml(Class<?> domainClass, Style style);
+ // end::refguide[]
/**
* Obtains a zip file of the serialized XML of the layouts (grids) of all domain entities and view models.
*/
+ // tag::refguide[]
byte[] toZip(final Style style);
+ // end::refguide[]
/**
* Obtains the serialized XML form of the menu bars layout ({@link MenuBarsService}).
* @param type - either the current menubars (could be loaded from a file) or the fallback (obtained from metamodel facets)
*/
+ // tag::refguide[]
String toMenuBarsXml(final MenuBarsService.Type type);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java b/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
index 963eafe..ef3ef9c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
@@ -33,10 +33,12 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface DeepLinkService {
+ // end::refguide[]
/**
* Creates a URI that can be used to obtain a representation of the provided domain object in one of the
* Isis viewers.
*/
+ // tag::refguide[]
URI deepLinkFor(Object domainObject);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
index baadf11..5ca9688 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
@@ -24,14 +24,18 @@ import org.apache.isis.applib.layout.menubars.bootstrap3.BS3MenuBars;
// tag::refguide[]
public interface MenuBarsLoaderService {
+ // end::refguide[]
/**
* Whether dynamic reloading of layouts is enabled.
*/
+ // tag::refguide[]
boolean supportsReloading();
+ // end::refguide[]
/**
* Returns a new instance of a {@link BS3MenuBars}, else <tt>null</tt>.
*/
+ // tag::refguide[]
BS3MenuBars menuBars();
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
index 940d762..10197af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
@@ -23,29 +23,34 @@ import org.apache.isis.applib.layout.menubars.MenuBars;
// tag::refguide[]
public interface MenuBarsService {
-// end::refguide[]
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Type {
+ // end::refguide-1[]
/**
* Either derived from annotations or as obtained elsewhere
* (eg using the {@link MenuBarsLoaderService} if the
* default implementation of this service is in use).
*/
+ // tag::refguide-1[]
DEFAULT,
+ // end::refguide-1[]
/**
* As derived from annotations.
*/
+ // tag::refguide-1[]
FALLBACK
}
-// end::refguide-1[]
-// tag::refguide[]
+ // end::refguide-1[]
+
/**
* Returns {@link #menuBars()} with a type of {@link Type#DEFAULT}.
* @return
*/
+ // tag::refguide[]
default MenuBars menuBars() {
return menuBars(Type.DEFAULT);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java b/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
index dcfc3dc..b2e32d6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
@@ -25,6 +25,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
// tag::refguide[]
public interface MessageService {
+ // end::refguide[]
/**
* Make the specified message available to the user. Note this will probably
* be displayed in transitory fashion, so is only suitable for useful but
@@ -34,8 +35,10 @@ public interface MessageService {
* @see #warnUser(String)
* @see #raiseError(String)
*/
+ // tag::refguide[]
void informUser(String message);
+ // end::refguide[]
/**
* Make the specified message available to the user, translated (if possible) to user's locale.
*
@@ -49,13 +52,17 @@ public interface MessageService {
* @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String informUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#informUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String informUser(TranslatableString message, final String translationContext);
+ // end::refguide[]
/**
* Warn the user about a situation with the specified message. The container
* should guarantee to display this warning to the user, and will typically
@@ -65,8 +72,10 @@ public interface MessageService {
* @see #raiseError(String)
* @see #informUser(String)
*/
+ // tag::refguide[]
void warnUser(String message);
+ // end::refguide[]
/**
* Warn the user about a situation with the specified message, translated (if possible) to user's locale.
*
@@ -80,13 +89,17 @@ public interface MessageService {
* @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String warnUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#warnUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String warnUser(TranslatableString message, final String translationContext);
+ // end::refguide[]
/**
* Notify the user of an application error with the specified message. Note
* this will probably be displayed in an alarming fashion, so is only
@@ -96,8 +109,10 @@ public interface MessageService {
* @see #warnUser(String)
* @see #informUser(String)
*/
+ // tag::refguide[]
void raiseError(String message);
+ // end::refguide[]
/**
* Notify the user of an application error with the specified message, translated (if possible) to user's locale.
*
@@ -111,11 +126,14 @@ public interface MessageService {
* @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
* @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
*/
+ // tag::refguide[]
String raiseError(TranslatableString message, final Class<?> contextClass, final String contextMethod);
+ // end::refguide[]
/**
* Override of {@link MessageService#raiseError(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
*/
+ // tag::refguide[]
String raiseError(TranslatableString message, final String translationContext);
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
index a696ab9..5a1f5a5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
@@ -18,37 +18,31 @@
*/
package org.apache.isis.applib.services.metamodel;
+// tag::refguide[]
public interface DomainMember extends Comparable<DomainMember> {
String getClassType();
String getClassName();
-
String getPackageName();
String getType();
String getMemberName();
-
String getNumParams();
boolean isContributed();
-
String getContributedBy();
boolean isMixedIn();
-
String getMixin();
String getHidden();
-
String getDisabled();
+ String getValidate();
String getChoices();
-
String getAutoComplete();
-
String getDefault();
-
- String getValidate();
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
index 0ba797f..2a0127d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
@@ -20,8 +20,10 @@ package org.apache.isis.applib.services.metamodel;
import java.util.List;
+// tag::refguide[]
public interface DomainModel {
List<DomainMember> getDomainMembers();
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
index 6d820b0..dd2ebf5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
@@ -43,18 +43,23 @@ import lombok.val;
// tag::refguide[]
public interface MetaModelService {
+ // end::refguide[]
/**
* Provides a reverse lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
*/
+ // tag::refguide[]
Class<?> fromObjectType(final String objectType);
+ // end::refguide[]
/**
* Provides a lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
*/
+ // tag::refguide[]
String toObjectType(final Class<?> domainType);
void rebuild(final Class<?> domainType);
+ // end::refguide[]
/**
* Returns a list of representations of each of member of each domain class.
*
@@ -67,6 +72,7 @@ public interface MetaModelService {
* </p>
*
*/
+ // tag::refguide[]
DomainModel getDomainModel();
BeanSort sortOf(Class<?> domainType, Mode mode);
@@ -75,22 +81,28 @@ public interface MetaModelService {
CommandDtoProcessor commandDtoProcessorFor(String memberIdentifier);
-// end::refguide[]
-
-// tag::refguide-1[]
+ // end::refguide[]
+ // tag::refguide-1[]
enum Mode {
+
+ // end::refguide-1[]
/**
* If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then throw an exception.
*/
+ // tag::refguide-1[]
STRICT,
+
+ // end::refguide-1[]
/**
* If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then return {@link Sort#UNKNOWN}.
*/
+ // tag::refguide-1[]
RELAXED
+
}
-// end::refguide-1[]
+ // end::refguide-1[]
-// tag::refguide-2[]
+ // tag::refguide-2[]
class Config {
private static final int IGNORE_NOOP_FACETS = 1;
@@ -182,10 +194,9 @@ public interface MetaModelService {
}
}
-// end::refguide-2[]
-
-// tag::refguide[]
+ // end::refguide-2[]
+ // tag::refguide[]
MetamodelDto exportMetaModel(final Config config);
}
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
index c80a5e8..17925aa 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
@@ -121,7 +121,9 @@ public class BookmarkServiceDefault implements BookmarkService, SerializingAdapt
if(bookmark == null) {
return null;
}
- //FIXME[2112] why would we ever store Service Beans as Bookmarks?
+ //FIXME[2112] why would we ever store Service Beans as Bookmarks?
+ // - ANSWER: because it might be used by the CommandService to replay a command or exec in the background.
+ //
// final String objectType = bookmark.getObjectType();
// final Object service = lookupService(objectType);
// if(service != null) {