Publish

1 files changed, 66 insertions, 0 deletions

diff --git a/jdisc_core/src/main/java/com/yahoo/jdisc/Container.java b/jdisc_core/src/main/java/com/yahoo/jdisc/Container.java
new file mode 100644
index 00000000000..53e9c76eb61
--- /dev/null
+++ b/jdisc_core/src/main/java/com/yahoo/jdisc/Container.java
@@ -0,0 +1,66 @@
+// Copyright 2016 Yahoo Inc. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
+package com.yahoo.jdisc;
+
+import com.google.inject.ConfigurationException;
+import com.google.inject.Key;
+import com.google.inject.ProvisionException;
+import com.yahoo.jdisc.application.Application;
+import com.yahoo.jdisc.application.BindingSet;
+import com.yahoo.jdisc.application.ContainerActivator;
+import com.yahoo.jdisc.application.ContainerBuilder;
+import com.yahoo.jdisc.handler.RequestHandler;
+import com.yahoo.jdisc.service.CurrentContainer;
+import com.yahoo.jdisc.service.ServerProvider;
+
+import java.net.URI;
+
+/**
+ * <p>This is the immutable Container. An instance of this class is attached to every {@link Request}, and as long as
+ * the {@link Request#release()} method has not been called, that Container instance is actively kept alive to prevent
+ * any race conditions during reconfiguration or shutdown. At any time there is only a single active Container in the
+ * running {@link Application}, and the only way to retrieve a reference to that Container is by calling {@link
+ * CurrentContainer#newReference(URI)}. Instead of holding a local Container object inside a {@link ServerProvider}
+ * (which will eventually become stale), use the {@link Request#Request(CurrentContainer, URI) appropriate Request
+ * constructor} instead.</p>
+ *
+ * <p>The only way to <u>create</u> a new instance of this class is to 1) create and configure a {@link
+ * ContainerBuilder}, and 2) pass that to the {@link ContainerActivator#activateContainer(ContainerBuilder)} method.</p>
+ *
+ * @author <a href="mailto:simon@yahoo-inc.com">Simon Thoresen</a>
+ */
+public interface Container extends SharedResource, Timer {
+
+    /**
+     * <p>Attempts to find a {@link RequestHandler} in the current server- (if {@link Request#isServerRequest()} is
+     * <em>true</em>) or client- (if {@link Request#isServerRequest()} is <em>false</em>) {@link BindingSet} that
+     * matches the given {@link URI}. If no match can be found, this method returns null.</p>
+     *
+     * @param request The Request to match against the bound {@link RequestHandler}s.
+     * @return The matching RequestHandler, or null if there is no match.
+     */
+    public RequestHandler resolveHandler(Request request);
+
+    /**
+     * <p>Returns the appropriate instance for the given injection key. When feasible, avoid using this method in favor
+     * of having Guice inject your dependencies ahead of time.</p>
+     *
+     * @param key  The key of the instance to return.
+     * @param <T>  The class of the instance to return.
+     * @return The appropriate instance of the given class.
+     * @throws ConfigurationException If this injector cannot find or create the provider.
+     * @throws ProvisionException     If there was a runtime failure while providing an instance.
+     */
+    public <T> T getInstance(Key<T> key);
+
+    /**
+     * <p>Returns the appropriate instance for the given injection type. When feasible, avoid using this method in
+     * favor of having Guice inject your dependencies ahead of time.</p>
+     *
+     * @param type The class object of the instance to return.
+     * @param <T>  The class of the instance to return.
+     * @return The appropriate instance of the given class.
+     * @throws ConfigurationException If this injector cannot find or create the provider.
+     * @throws ProvisionException     If there was a runtime failure while providing an instance.
+     */
+    public <T> T getInstance(Class<T> type);
+}