From e400ad695ebd6fa3d315fb8b550c25d61860f9e6 Mon Sep 17 00:00:00 2001 From: Marco Collovati Date: Tue, 22 Mar 2022 14:32:24 +0100 Subject: [PATCH] chore: Adding missing javadocs Part of #15 --- .../vaadin/quarkus/QuarkusInstantiator.java | 21 ++++++++++ .../quarkus/QuarkusResourceProvider.java | 4 ++ .../vaadin/quarkus/QuarkusVaadinServlet.java | 10 +++++ .../quarkus/QuarkusVaadinServletService.java | 23 +++++++++++ .../quarkus/context/AbstractContext.java | 5 +++ .../AbstractContextualStorageManager.java | 41 +++++++++++++++++++ 6 files changed, 104 insertions(+) diff --git a/runtime/src/main/java/com/vaadin/quarkus/QuarkusInstantiator.java b/runtime/src/main/java/com/vaadin/quarkus/QuarkusInstantiator.java index 1a592da..298ec06 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/QuarkusInstantiator.java +++ b/runtime/src/main/java/com/vaadin/quarkus/QuarkusInstantiator.java @@ -33,6 +33,17 @@ import com.vaadin.flow.server.VaadinServiceInitListener; import com.vaadin.quarkus.annotation.VaadinServiceEnabled; +/** + * Instantiator implementation based on Quarkus DI feature. + * + * Quarkus DI solution (also called ArC) is based on the Contexts and Dependency + * Injection for Java 2.0 specification, but it is not a full CDI + * implementation. Only a subset of the CDI features is implemented. + * + * See {@link https://quarkus.io/guides/cdi-reference} for details. + * + * @see Instantiator + */ @VaadinServiceEnabled @Unremovable @ApplicationScoped @@ -47,10 +58,20 @@ public class QuarkusInstantiator implements Instantiator { @Inject BeanManager beanManager; + /** + * Gets the service class that this instantiator is supposed to work with. + * + * @return the service class this instantiator is supposed to work with. + */ public Class getServiceClass() { return QuarkusVaadinServletService.class; } + /** + * Gets the {@link BeanManager} instance. + * + * @return the {@link BeanManager} instance. + */ public BeanManager getBeanManager() { return this.beanManager; } diff --git a/runtime/src/main/java/com/vaadin/quarkus/QuarkusResourceProvider.java b/runtime/src/main/java/com/vaadin/quarkus/QuarkusResourceProvider.java index c3d36de..e7a1b6d 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/QuarkusResourceProvider.java +++ b/runtime/src/main/java/com/vaadin/quarkus/QuarkusResourceProvider.java @@ -29,6 +29,10 @@ import com.vaadin.flow.di.ResourceProvider; +/** + * A {@link ResourceProvider} implementation that delegates resource loading to + * current thread context ClassLoader. + */ public class QuarkusResourceProvider implements ResourceProvider { private Map cache = new ConcurrentHashMap<>(); diff --git a/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServlet.java b/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServlet.java index 893c3c1..42b3122 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServlet.java +++ b/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServlet.java @@ -30,6 +30,16 @@ import com.vaadin.flow.server.VaadinServlet; import com.vaadin.flow.server.VaadinServletService; +/** + * Servlet to create {@link QuarkusVaadinServletService}. + * + * An instance of this servlet is automatically registered if no other custom + * VaadinServlet class with Servlet 3.0 annotations is present on classpath. A + * subclass of this servlet can be to provide a customized + * {@link QuarkusVaadinServletService} implementation, in which case + * {@link #createServletService(DeploymentConfiguration)} must call + * {@code service.init()}. + */ public class QuarkusVaadinServlet extends VaadinServlet { @Inject diff --git a/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServletService.java b/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServletService.java index baa03f5..9418a79 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServletService.java +++ b/runtime/src/main/java/com/vaadin/quarkus/QuarkusVaadinServletService.java @@ -50,6 +50,15 @@ import com.vaadin.flow.server.VaadinServletService; import com.vaadin.flow.server.VaadinSession; +/** + * An implementation of {@link com.vaadin.flow.server.VaadinService} for Quarkus + * environment. + * + * This class looks up for and therefore provides an {@link Instantiator} bean. + * It also forwards Vaadin events to CDI listeners. + * + * @author Vaadin Ltd + */ public class QuarkusVaadinServletService extends VaadinServletService { private BeanManager beanManager; @@ -163,6 +172,20 @@ private void addUIListeners(UI ui) { ui.addPollListener(uiEventListener); } + /** + * Gets an instance of a {@code @VaadinServiceEnabled} annotated bean of the + * given {@code type}. + * + * @param type + * the required service type + * @param + * the type of the service + * @return an {@link Optional} wrapping the service instance, or + * {@link Optional#empty()} if no bean definition exists for given + * type. + * @throws ServiceException + * if multiple beans exists for the given type. + */ public Optional lookup(Class type) throws ServiceException { try { T instance = new BeanLookup<>(getBeanManager(), type, diff --git a/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContext.java b/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContext.java index 87afafd..a59ecdb 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContext.java +++ b/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContext.java @@ -59,6 +59,11 @@ public abstract class AbstractContext implements InjectableContext { protected abstract ContextualStorage getContextualStorage( Contextual contextual, boolean createIfNotExist); + /** + * Gets all active contextual storages. + * + * @return a list of contextual storages. + */ protected List getActiveContextualStorages() { List result = new ArrayList(); result.add(getContextualStorage(null, false)); diff --git a/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContextualStorageManager.java b/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContextualStorageManager.java index 701058c..95727dd 100644 --- a/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContextualStorageManager.java +++ b/runtime/src/main/java/com/vaadin/quarkus/context/AbstractContextualStorageManager.java @@ -46,6 +46,18 @@ protected AbstractContextualStorageManager(boolean concurrent) { this.concurrent = concurrent; } + /** + * Gets the {@link ContextualStorage} associated with the given context + * {@code key}, possibly creating a new instance, if requested and not + * already existing. + * + * @param key + * context key + * @param createIfNotExist + * whether a ContextualStorage shall get created if it doesn't + * yet exist. + * @return a {@link ContextualStorage} instance. + */ protected ContextualStorage getContextualStorage(K key, boolean createIfNotExist) { if (createIfNotExist) { @@ -55,6 +67,14 @@ protected ContextualStorage getContextualStorage(K key, } } + /** + * Changes the context key for a contextual storage. + * + * @param from + * the contextual storage context key + * @param to + * the new context for the contextual storage + */ protected void relocate(K from, K to) { ContextualStorage storage = storageMap.remove(from); if (storage != null) { @@ -62,10 +82,20 @@ protected void relocate(K from, K to) { } } + /** + * Creates a new {@link ContextualStorage} for the given context key. + * + * @param key + * the context key + * @return a new {@link ContextualStorage} instance. + */ protected ContextualStorage newContextualStorage(K key) { return new ContextualStorage(concurrent); } + /** + * Destroys all existing contextual storages. + */ @PreDestroy protected void destroyAll() { Collection storages = storageMap.values(); @@ -75,6 +105,12 @@ protected void destroyAll() { storageMap.clear(); } + /** + * Destroys the contextual storage associated with the given context key. + * + * @param key + * the context key + */ protected void destroy(K key) { ContextualStorage storage = storageMap.remove(key); if (storage != null) { @@ -82,6 +118,11 @@ protected void destroy(K key) { } } + /** + * Gets context keys of all registered contextual storages. + * + * @return immutable set of context keys. + */ protected Set getKeySet() { return Collections.unmodifiableSet(storageMap.keySet()); }