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/01/26 15:57:47 UTC
[isis] 12/14: ISIS-2062: sync adoc examples
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 b7c3ce71491b2b67ff32396896c65fd7fba1a6cd
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jan 26 15:31:11 2020 +0000
ISIS-2062: sync adoc examples
---
.../applib-ant/examples/annotation/HomePage.java | 15 +++---
.../mixins/metamodel/Object_objectIdentifier.java | 16 ++++--
.../examples/services/factory/FactoryService.java | 61 +++++++++++++++++-----
.../services/health/HealthCheckService.java | 3 --
4 files changed, 67 insertions(+), 28 deletions(-)
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
index 05b4954..9bad1d7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
@@ -28,19 +28,16 @@ import java.lang.annotation.Target;
import org.apache.isis.applib.ViewModel;
/**
- * Indicates that the (no-arg) action (on a domain service) to be invoked automatically
- * and the contents used for the home page.
+ * Annotated on a view model to indicate that it should be used as the home page.
*
* <p>
- * Typically this action would return a {@link ViewModel} representing a dashboard
- * (from which the user can navigate to commonly used objects and invoked actions);
- * it might also simply invoke an action that returns a list.
- * <p>
- * Might also be placed on a type typically a {@link ViewModel} to be used as the home page.
- *
+ * The view model is instantiated through a no-arg constructor, so must in effect be stateless.
+ * Typically it will use injected repositories in order to display a dashboard, and offer actions
+ * to traverse or operate on the rendered state.
+ * </p>
*/
@Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE })
+@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
public @interface HomePage {
}
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/mixins/metamodel/Object_objectIdentifier.java b/api/applib/src/main/adoc/modules/applib-cm/examples/mixins/metamodel/Object_objectIdentifier.java
index eef7817..de8a9f2 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/mixins/metamodel/Object_objectIdentifier.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/mixins/metamodel/Object_objectIdentifier.java
@@ -33,6 +33,7 @@ import org.apache.isis.applib.services.bookmark.BookmarkService;
import org.apache.isis.applib.services.metamodel.MetaModelService;
import org.apache.isis.core.commons.internal.base._Strings;
+import lombok.NonNull;
import lombok.RequiredArgsConstructor;
import lombok.val;
@@ -60,10 +61,19 @@ public class Object_objectIdentifier {
public String prop() {
val bookmark = bookmarkService.bookmarkForElseThrow(this.holder);
val sort = mmService.sortOf(bookmark, MetaModelService.Mode.RELAXED);
- if(sort.isEntity()) {
- return bookmark.getIdentifier();
+ if(!sort.isEntity()) {
+ return shortend(bookmark.getIdentifier());
}
- return _Strings.ellipsifyAtStart(bookmark.getIdentifier(), 16, "…");
+ return bookmark.getIdentifier();
+ }
+
+ // -- HELPER
+
+ private String shortend(@NonNull String identifier) {
+
+ val hashHexed = Integer.toHexString(identifier.hashCode());
+ val hashPadded = _Strings.padStart(hashHexed, 8, '0');
+ return "»" + hashPadded;
}
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 4214b3f..5d86540 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,18 +23,35 @@ import java.util.NoSuchElementException;
import javax.annotation.Nullable;
-import org.apache.isis.applib.services.repository.RepositoryService;
import org.apache.isis.core.commons.exceptions.IsisException;
public interface FactoryService {
/**
+ * Carefree 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)}
+ * based on the type's meta-data.
+ * @param <T>
+ * @param requiredType
+ * @return
+ * @throws NoSuchElementException if result is empty
+ * @throws IsisException if instance creation failed
+ * @throws IllegalArgumentException if requiredType is not recognized by the meta-model
+ *
+ * @since 2.0
+ *
+ */
+ <T> T getOrCreate(Class<T> requiredType);
+
+ /**
* 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
+ * @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)
*
@@ -42,42 +59,50 @@ public interface FactoryService {
* @throws IsisException if instance creation failed
*
* @apiNote does not force the requiredType to be added to the meta-model
- *
* @since 2.0
*/
<T> T get(Class<T> requiredType);
/**
- * Creates a new detached entity instance, with injection points resolved.
+ * Creates a new detached entity instance, with injection points resolved
+ * and defaults applied.
* @param <T>
- * @param domainClass
+ * @param domainClass - only applicable to entity types
* @return
+ * @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
*/
<T> T detachedEntity(Class<T> domainClass);
/**
- * Creates a new Mixin instance.
+ * Creates a new Mixin instance, with injection points resolved.
* @param <T>
* @param mixinClass
* @param mixedIn
* @return
+ * @throws IllegalArgumentException if mixinClass is not a mixin type
* @apiNote forces the mixinClass to be added to the meta-model if not already
*/
<T> T mixin(Class<T> mixinClass, Object mixedIn);
/**
- * Creates a new ViewModel instance, and initializes 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
*/
<T> T viewModel(Class<T> viewModelClass, @Nullable String mementoStr);
/**
- * Creates a new ViewModel instance
+ * Creates a new ViewModel instance,
+ * with injection points resolved
+ * 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
*/
@@ -85,8 +110,19 @@ public interface FactoryService {
return viewModel(viewModelClass, /*mementoStr*/null);
}
+ /**
+ * 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 not an IoC container managed type
+ * @apiNote forces the domainClass to be added to the meta-model if not already
+ * @since 2.0
+ */
+ <T> T create(Class<T> domainClass);
+
// -- DEPRECATIONS
-
+
/**
* Creates a new instance of the specified class, but does not persist it.
*
@@ -115,12 +151,11 @@ public interface FactoryService {
* method.
* </p>
* @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
- * instead consider use of {@link #detachedEntity(Class)} if applicable
+ * instead consider use of {@link #getOrCreate(Class)} if applicable
*/
@Deprecated
default <T> T instantiate(Class<T> domainClass) {
- return detachedEntity(domainClass);
+ return getOrCreate(domainClass);
}
-
-
+
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/HealthCheckService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/HealthCheckService.java
index f197b5c..80c0adb 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/HealthCheckService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/HealthCheckService.java
@@ -20,9 +20,6 @@ package org.apache.isis.applib.services.health;
import org.apache.isis.applib.annotation.Programmatic;
-/**
- * SPI. If implemented then <code>/restful/health</code> resource will invoke this service to determine the health of the system.
- */
public interface HealthCheckService {
@Programmatic