Author: struberg
Date: Mon Aug 29 12:33:26 2011
New Revision: 1162761
URL: http://svn.apache.org/viewvc?rev=1162761&view=rev
Log:
OWB-571 improve SPI documentation
Added:
openwebbeans/trunk/webbeans-spi/src/site/apt/
openwebbeans/trunk/webbeans-spi/src/site/apt/configuration.apt
openwebbeans/trunk/webbeans-spi/src/site/apt/index.apt
Modified:
openwebbeans/trunk/webbeans-spi/src/main/java/org/apache/webbeans/spi/ContainerLifecycle.java
Modified:
openwebbeans/trunk/webbeans-spi/src/main/java/org/apache/webbeans/spi/ContainerLifecycle.java
URL:
http://svn.apache.org/viewvc/openwebbeans/trunk/webbeans-spi/src/main/java/org/apache/webbeans/spi/ContainerLifecycle.java?rev=1162761&r1=1162760&r2=1162761&view=diff
==============================================================================
---
openwebbeans/trunk/webbeans-spi/src/main/java/org/apache/webbeans/spi/ContainerLifecycle.java
(original)
+++
openwebbeans/trunk/webbeans-spi/src/main/java/org/apache/webbeans/spi/ContainerLifecycle.java
Mon Aug 29 12:33:26 2011
@@ -23,9 +23,14 @@ import java.util.Properties;
import javax.enterprise.inject.spi.BeanManager;
/**
- * JSR-299 Container lifecycle.
- *
- * @version $Rev$ $Date$
+ * <h3>JSR-299 Container lifecycle.</h3>
+ * <p>
+ * Implement this interface to provide own container initialization logic.
+ * </p>
+ * <p>
+ * From the application point of view this interface can be used to start
+ * and stop OpenWebBeans.
+ * </p>
*
*/
public interface ContainerLifecycle
@@ -42,11 +47,11 @@ public interface ContainerLifecycle
/**
* Starts container. It discovers all beans
- * in the deployment archive.
+ * in the deployed application classpath.
* <p>
* For Java EE artifact deployment, it scans all classes
- * and libraries in the deployment archive. There are several
- * types of deployment arhives;
+ * and libraries in all deployment archives in the classpath.
+ * There are several types of deployment archives;
* <ul>
* <li>EAR archive</li>
* <li>EJB archive</li>
@@ -55,33 +60,43 @@ public interface ContainerLifecycle
* <li>Application client archive. <b>OPTIONAL</b></li>
* </ul>
* </p>
- *
+ *
* <p>
- * Container uses metadata discovery SPI for scanning archives
+ * Container uses {@link ScannerService} SPI for scanning archives
* and act accordingly. If there is an exception while starting,
* it must abort the deployment and provides information to the
* developer.
* </p>
+ *
* @param startupObject any startup object.
*/
public void startApplication(Object startupObject);
/**
- * Stops means that container removes all bean instances
- * it store, remove contexts and does necessary final actions.
- * @param endObject any onject provided by implementors
+ * <p>
+ * Stopping the Application means that the container destroys all bean
instances
+ * it stores, cleans and removes all contexts and does other necessary
+ * cleanup actions.
+ * </p>
+ * <p>
+ * <b>Attention:</b> Accessing the BeanManager or any bean proxy after the
shutdown
+ * will result in non-portable behaviour!
+ * </p>
+ * @param endObject any object provided by application implementor. This
can be a ServletContext, etc
*/
public void stopApplication(Object endObject);
/**
- * Gets deployment bean manager instance. There is 1-1 correspondence
- * between bean manager and deployment archive.
+ * Get the underlying {@link BeanManager} instance for the current
application.
+ * There is 1-1 correspondence between a bean manager and a deployed
(web-) application.
* @return deployment {@link BeanManager} instance
*/
public BeanManager getBeanManager();
/**
* Gets container's context service implementation.
+ * This allows to manually start and end specific contexts.
+ *
* @return container contexts service
*/
public ContextsService getContextService();
Added: openwebbeans/trunk/webbeans-spi/src/site/apt/configuration.apt
URL:
http://svn.apache.org/viewvc/openwebbeans/trunk/webbeans-spi/src/site/apt/configuration.apt?rev=1162761&view=auto
==============================================================================
--- openwebbeans/trunk/webbeans-spi/src/site/apt/configuration.apt (added)
+++ openwebbeans/trunk/webbeans-spi/src/site/apt/configuration.apt Mon Aug 29
12:33:26 2011
@@ -0,0 +1,12 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with this
+~~ work for additional information regarding copyright ownership. The ASF
+~~ licenses this file to You under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance with the License.
+~~ You may obtain a copy of the License at
+~~ http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
+~~ or agreed to in writing, software distributed under the License is
+~~ distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the specific language
+~~ governing permissions and limitations under the License.
+Apache OpenWebBeans Configuration Mechanism
Added: openwebbeans/trunk/webbeans-spi/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/openwebbeans/trunk/webbeans-spi/src/site/apt/index.apt?rev=1162761&view=auto
==============================================================================
--- openwebbeans/trunk/webbeans-spi/src/site/apt/index.apt (added)
+++ openwebbeans/trunk/webbeans-spi/src/site/apt/index.apt Mon Aug 29 12:33:26
2011
@@ -0,0 +1,27 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one or more
+~~ contributor license agreements. See the NOTICE file distributed with this
+~~ work for additional information regarding copyright ownership. The ASF
+~~ licenses this file to You under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance with the License.
+~~ You may obtain a copy of the License at
+~~ http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
+~~ or agreed to in writing, software distributed under the License is
+~~ distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the specific language
+~~ governing permissions and limitations under the License.
+Apache OpenWebBeans Service Provider Interfaces
+
+* Architectural Overview
+
+ Apache OpenWebBeans is modular built using Java interfaces with multiple
available
+ implementations.
+
+ The implementation to use can be set via our
+ {{{./configuration.html}Configuration Mechanism}}
+
+
+* Available SPIs
+
+ The list of availabe service provider interfaces and the documentation can
+ be found in our {{{./apidocs/index.html}JavaDoc}}.
+
