commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From joc...@apache.org
Subject svn commit: r1636587 - in /commons/sandbox/commons-inject/trunk/src/site: ./ apt/ apt/index.apt apt/using.apt site.xml
Date Tue, 04 Nov 2014 14:34:28 GMT
Author: jochen
Date: Tue Nov  4 14:34:28 2014
New Revision: 1636587

URL: http://svn.apache.org/r1636587
Log:
Adding preliminary site.

Added:
    commons/sandbox/commons-inject/trunk/src/site/
    commons/sandbox/commons-inject/trunk/src/site/apt/
    commons/sandbox/commons-inject/trunk/src/site/apt/index.apt
    commons/sandbox/commons-inject/trunk/src/site/apt/using.apt
    commons/sandbox/commons-inject/trunk/src/site/site.xml   (with props)

Added: commons/sandbox/commons-inject/trunk/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-inject/trunk/src/site/apt/index.apt?rev=1636587&view=auto
==============================================================================
--- commons/sandbox/commons-inject/trunk/src/site/apt/index.apt (added)
+++ commons/sandbox/commons-inject/trunk/src/site/apt/index.apt Tue Nov  4 14:34:28 2014
@@ -0,0 +1,45 @@
+     ---------------------
+     Apache Commons Inject
+     ---------------------
+
+Apache Commons Inject is an implementation of {{{https://jcp.org/en/jsr/detail?id=330}JSR
330: Dependency Injection for Java}}.
+In other words: It is yet another implementation of JSR 330, much like
+{{{https://code.google.com/p/google-guice/}Guice}},
+{{{http://www.mkyong.com/spring3/spring-3-and-jsr-330-inject-and-named-example/}Spring}},
+{{{http://square.github.io/dagger/}Dagger}}, and some minor others.
+
+Commons Inject mimicks Guice in most aspects. (For example, if you know the Guice API,
+you will immediately understand the API of Commons Inject.) However, compared to Guice,
+you will hopefully note the following differences:
+
+* Commons Inject is self contained. You don't need Guava, or similar helper jar files.
+* Commons Inject is somewhat easier to use. In particular, you don't need to bother so
+  much about Generics. OTOH, there's no automatic distinction between
+
+------------------------------------
+  @Inject private List someList;
+  @Inject private List<Foo> fooList;
+------------------------------------
+
+  However, that distinction isn't part of JSR 330, anyways. Instead it is suggested
+  that you use the concept of names:
+
+------------------------------------
+  @Inject private List someList;
+  @Inject @Named(value="foo") private List<Foo> fooList;
+------------------------------------
+ 
+* Commons Inject is based on the standard Java reflection API <<only>>. As a
consequence, it
+  should work on Android.
+* Commons Inject doesn't distinguish between production mode, and development mode.
+  OTOH, its startup time should be <<much>> faster than Guice in production mode.
+* Commons Inject provides some extensions out of the box:
+  * Support for an {{{./lifecycle.html}Application Lifecycle}}, including support for
+    {{{http://docs.oracle.com/javaee/5/api/javax/annotation/PostConstruct.html}@PostConstruct}},
+    and {{{http://docs.oracle.com/javaee/5/api/javax/annotation/PreDestroy.html}@PreDestroy}}.
+    This lifecycle support works with arbitrary objects, including eager, or lazy
+    singletons.
+  * {{{./loggerInjection.html}Logger injection}} via Log4J, SLF4J, or Commons Logging.
+    (Adding support for other frameworks should be extremely easy.)
+
+     
\ No newline at end of file

Added: commons/sandbox/commons-inject/trunk/src/site/apt/using.apt
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-inject/trunk/src/site/apt/using.apt?rev=1636587&view=auto
==============================================================================
--- commons/sandbox/commons-inject/trunk/src/site/apt/using.apt (added)
+++ commons/sandbox/commons-inject/trunk/src/site/apt/using.apt Tue Nov  4 14:34:28 2014
@@ -0,0 +1,65 @@
+     --------------------
+     Using Commons Inject
+     --------------------
+
+To use Commons Inject, you have to create an
+{{{./apidocs/org/apache/commons/inject/api/IInjector.html}IInjector}}. The purpose
+of the IInjector is the creation of POJO's, according to the rules you specify.
+The IInjector is the direct equivalent of the {{{}Guice Injector}}.
+
+To create an Injector, you must have some modules that provide the injectors
+configurtion. There are a few predefined modules:
+
+[[PostConstructModule]] The {{{./apidocs/org/apache/commons/inject/api/PostConstructModule.html}
+  PostConstruct module}} provides support for an application lifecycle: Your POJO's
+  may be initialized when the aplication starts. And there is also the possibility
+  for a shutdown. See {{{./lifecycle.html}this document}} for details.
+[[Log4jLoggerModule]]  The {{{./apidocs/org/apache/commons/inject/api/Log4jLoggerModule.html}
+  Log4j Logger module}} allows to have Log4j Loggers injected into your POJO's.
+  Details are described {{{./loggerInjection.html}here}}.
+
+Of course, the predefined modules will never be sufficient. In practice, you will also
+have custom modules like this:
+
+----------------------------------------------
+package com.foo.myapp;
+
+import org.apache.commons.inject.api.IModule;
+import org.apache.commons.inject.api.bind.IBinder;
+
+public class MyModule implements IModule {
+  @Override
+  public void configure(IBinder pBinder) {
+    pBinder.setDefaultScope(Scopes.PER_CALL);
+    pBinder.bind(List.class).to(ArrayList.class);
+    pBinder.bind(List.class, "linked").to(LinkedList.class);
+    ... // More bindings.
+  }
+}
+----------------------------------------------
+
+Assuming that you have created your modules, and you wish to use one or more
+of the predefined module, then you can create an IInjector like this:
+
+----------------------------------------------
+import org.apache.commons.inject.api.CommonsInject;
+import org.apache.commons.inject.api.IInjector;
+
+public IInjector newInjector() {
+  PostConstructModule module0 = new PostConstructModule();
+  Log4jLoggerModule module1 = new Log4jLoggerModule();
+  MyModule module2 = new MyModule();
+  return CommonsInject.build(module0, module1, module2);
+----------------------------------------------
+
+That Injector can create POJO's for you, like this:
+
+----------------------------------------------
+  List<Foo> fooList = injector.requireInstance(List.class);
+  List<Bar> barList = injector.requireInstance(List.class, "linked");
+----------------------------------------------
+
+  According to the above configuration, fooList will be an instance
+  of java.util.ArrayList, but barList will be a java.util.LinkedList.
+  
+  
\ No newline at end of file

Added: commons/sandbox/commons-inject/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-inject/trunk/src/site/site.xml?rev=1636587&view=auto
==============================================================================
--- commons/sandbox/commons-inject/trunk/src/site/site.xml (added)
+++ commons/sandbox/commons-inject/trunk/src/site/site.xml Tue Nov  4 14:34:28 2014
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project name="Commons Inject" xmlns="http://maven.apache.org/DECORATION/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd">
+
+  <bannerRight>
+    <name>Commons Inject</name>
+    <src>/images/logo.png</src>
+    <href>/index.html</href>
+  </bannerRight>
+
+  <body>
+    <menu name="Commons Inject">
+      <item name="Overview"                 href="/index.html" />
+      <item name="User guide"               href="/using.html" />
+      <item name="Lifecycle handling"       href="/lifycycle.html" />
+      <item name="Logger injection"         href="/loggerInjection.html" />
+      <item name="FAQ"                      href="/faq.html" />
+      <item name="Javadoc"                  href="/apidocs/index.html" />
+      <item name="Download"                 href="/download.html" />
+      <item name="Mailing lists"            href="/mail-lists.html" />
+      <item name="Issue Tracking"           href="/issue-tracking.html" />
+      <item name="Team"                     href="/team-list.html" />
+      <item name="SVN repository"           href="/source-repository.html" />
+    </menu>
+
+	<menu ref="parent"/>
+  </body>
+
+</project>

Propchange: commons/sandbox/commons-inject/trunk/src/site/site.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message