From d53f42e880ca05a483e68d88224c89b3f36bca43 Mon Sep 17 00:00:00 2001 From: Bob Lee Date: Tue, 13 Oct 2009 19:55:36 +0000 Subject: Uploaded final spec. git-svn-id: https://atinject.googlecode.com/svn/trunk@56 3bc8319c-20ab-11de-9edc-3f40a397ab60 --- javadoc/allclasses-frame.html | 40 ++++ javadoc/allclasses-noframe.html | 40 ++++ javadoc/constant-values.html | 138 +++++++++++++ javadoc/deprecated-list.html | 138 +++++++++++++ javadoc/help-doc.html | 205 ++++++++++++++++++ javadoc/index-all.html | 171 +++++++++++++++ javadoc/index.html | 36 ++++ javadoc/javax/inject/Inject.html | 317 ++++++++++++++++++++++++++++ javadoc/javax/inject/Named.html | 210 +++++++++++++++++++ javadoc/javax/inject/Provider.html | 234 +++++++++++++++++++++ javadoc/javax/inject/Qualifier.html | 194 +++++++++++++++++ javadoc/javax/inject/Scope.html | 215 +++++++++++++++++++ javadoc/javax/inject/Singleton.html | 169 +++++++++++++++ javadoc/javax/inject/package-frame.html | 51 +++++ javadoc/javax/inject/package-summary.html | 332 ++++++++++++++++++++++++++++++ javadoc/javax/inject/package-tree.html | 150 ++++++++++++++ javadoc/overview-tree.html | 152 ++++++++++++++ javadoc/package-list | 1 + javadoc/resources/inherit.gif | Bin 0 -> 57 bytes javadoc/stylesheet.css | 29 +++ 20 files changed, 2822 insertions(+) create mode 100644 javadoc/allclasses-frame.html create mode 100644 javadoc/allclasses-noframe.html create mode 100644 javadoc/constant-values.html create mode 100644 javadoc/deprecated-list.html create mode 100644 javadoc/help-doc.html create mode 100644 javadoc/index-all.html create mode 100644 javadoc/index.html create mode 100644 javadoc/javax/inject/Inject.html create mode 100644 javadoc/javax/inject/Named.html create mode 100644 javadoc/javax/inject/Provider.html create mode 100644 javadoc/javax/inject/Qualifier.html create mode 100644 javadoc/javax/inject/Scope.html create mode 100644 javadoc/javax/inject/Singleton.html create mode 100644 javadoc/javax/inject/package-frame.html create mode 100644 javadoc/javax/inject/package-summary.html create mode 100644 javadoc/javax/inject/package-tree.html create mode 100644 javadoc/overview-tree.html create mode 100644 javadoc/package-list create mode 100644 javadoc/resources/inherit.gif create mode 100644 javadoc/stylesheet.css diff --git a/javadoc/allclasses-frame.html b/javadoc/allclasses-frame.html new file mode 100644 index 0000000..4ca289e --- /dev/null +++ b/javadoc/allclasses-frame.html @@ -0,0 +1,40 @@ + + + + + + +All Classes + + + + + + + + + + +All Classes +
+ + + + + +
Inject +
+Named +
+Provider +
+Qualifier +
+Scope +
+Singleton +
+
+ + + diff --git a/javadoc/allclasses-noframe.html b/javadoc/allclasses-noframe.html new file mode 100644 index 0000000..fd88343 --- /dev/null +++ b/javadoc/allclasses-noframe.html @@ -0,0 +1,40 @@ + + + + + + +All Classes + + + + + + + + + + +All Classes +
+ + + + + +
Inject +
+Named +
+Provider +
+Qualifier +
+Scope +
+Singleton +
+
+ + + diff --git a/javadoc/constant-values.html b/javadoc/constant-values.html new file mode 100644 index 0000000..ab18110 --- /dev/null +++ b/javadoc/constant-values.html @@ -0,0 +1,138 @@ + + + + + + +Constant Field Values + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Constant Field Values

+
+
+Contents + +
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/deprecated-list.html b/javadoc/deprecated-list.html new file mode 100644 index 0000000..4c96eb7 --- /dev/null +++ b/javadoc/deprecated-list.html @@ -0,0 +1,138 @@ + + + + + + +Deprecated List + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree   Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Deprecated API

+
+
+Contents + +
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree   Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/help-doc.html b/javadoc/help-doc.html new file mode 100644 index 0000000..f489f5c --- /dev/null +++ b/javadoc/help-doc.html @@ -0,0 +1,205 @@ + + + + + + +API Help + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index   Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+How This API Document Is Organized

+
+This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

+Package

+
+ +

+Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

+
+

+Class/Interface

+
+ +

+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+ +

+Annotation Type

+
+ +

+Each annotation type has its own separate page with the following sections:

+
+ +

+Enum

+
+ +

+Each enum has its own separate page with the following sections:

+
+

+Tree (Class Hierarchy)

+
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object. +
+

+Deprecated API

+
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+

+Index

+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+

+Prev/Next

+These links take you to the next or previous class, interface, package, or related page.

+Frames/No Frames

+These links show and hide the HTML frames. All pages are available with or without frames. +

+

+Serialized Form

+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description. +

+

+Constant Field Values

+The Constant Field Values page lists the static final fields and their values. +

+ + +This help file applies to API documentation generated using the standard doclet. + +
+

+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index   Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/index-all.html b/javadoc/index-all.html new file mode 100644 index 0000000..23639fe --- /dev/null +++ b/javadoc/index-all.html @@ -0,0 +1,171 @@ + + + + + + +Index + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated   Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +G I J N P Q S
+

+G

+
+
get() - +Method in interface javax.inject.Provider +
Provides a fully-constructed and injected instance of T. +
+
+

+I

+
+
Inject - Annotation Type in javax.inject
Identifies injectable constructors, methods, and fields.
+
+

+J

+
+
javax.inject - package javax.inject
This package specifies a means for obtaining objects in such a way as to + maximize reusability, testability and maintainability compared to + traditional approaches such as constructors, factories, and service + locators (e.g., JNDI). This process, known as dependency + injection, is beneficial to most nontrivial applications.
+
+

+N

+
+
Named - Annotation Type in javax.inject
String-based qualifier.
+
+

+P

+
+
Provider<T> - Interface in javax.inject
Provides instances of T.
+
+

+Q

+
+
Qualifier - Annotation Type in javax.inject
Identifies qualifier annotations.
+
+

+S

+
+
Scope - Annotation Type in javax.inject
Identifies scope annotations.
Singleton - Annotation Type in javax.inject
Identifies a type that the injector only instantiates once.
+
+G I J N P Q S + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated   Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/index.html b/javadoc/index.html new file mode 100644 index 0000000..a5979c3 --- /dev/null +++ b/javadoc/index.html @@ -0,0 +1,36 @@ + + + + + + +Generated Documentation (Untitled) + + + + + + + + +<H2> +Frame Alert</H2> + +<P> +This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client. +<BR> +Link to<A HREF="javax/inject/package-summary.html">Non-frame version.</A> + + + diff --git a/javadoc/javax/inject/Inject.html b/javadoc/javax/inject/Inject.html new file mode 100644 index 0000000..061999e --- /dev/null +++ b/javadoc/javax/inject/Inject.html @@ -0,0 +1,317 @@ + + + + + + +Inject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+ +

+ +javax.inject +
+Annotation Type Inject

+
+
+
@Target(value={METHOD,CONSTRUCTOR,FIELD})
+@Retention(value=RUNTIME)
+@Documented
+public @interface Inject
+ + +

+Identifies injectable constructors, methods, and fields. May apply to static + as well as instance members. An injectable member may have any access + modifier (private, package-private, protected, public). Constructors are + injected first, followed by fields, and then methods. Fields and methods + in superclasses are injected before those in subclasses. Ordering of + injection among fields and among methods in the same class is not specified. + +

Injectable constructors are annotated with @Inject and accept + zero or more dependencies as arguments. @Inject can apply to at most + one constructor per class. + +

@Inject + ConstructorModifiersopt + SimpleTypeName(FormalParameterListopt) + Throwsopt + ConstructorBody
+ +

@Inject is optional for public, no-argument constructors when no + other constructors are present. This enables injectors to invoke default + constructors. + +

+ @Injectopt + Annotationsopt + public + SimpleTypeName() + Throwsopt + ConstructorBody
+ +

Injectable fields: +

+ +

@Inject + FieldModifiersopt + Type + VariableDeclarators;
+ +

Injectable methods: +

+ +

@Inject + MethodModifiersopt + ResultType + Identifier(FormalParameterListopt) + Throwsopt + MethodBody
+ +

The injector ignores the result of an injected method, but + non-void return types are allowed to support use of the method in + other contexts (builder-style method chaining, for example). + +

Examples: + + 

+   public class Car {
+     // Injectable constructor
+     @Inject public Car(Engine engine) { ... }
+
+     // Injectable field
+     @Inject private Provider<Seat> seatProvider;
+
+     // Injectable package-private method
+     @Inject void install(Windshield windshield, Trunk trunk) { ... }
+   }
+ +

A method annotated with @Inject that overrides another method + annotated with @Inject will only be injected once per injection + request per instance. A method with no @Inject annotation + that overrides a method annotated with @Inject will not be + injected. + +

Injection of members annotated with @Inject is required. While an + injectable member may use any accessibility modifier (including + private), platform or injector limitations (like security + restrictions or lack of reflection support) might preclude injection + of non-public members. + +

Qualifiers

+ +

A qualifier may annotate an injectable field + or parameter and, combined with the type, identify the implementation to + inject. Qualifiers are optional, and when used with @Inject in + injector-independent classes, no more than one qualifier should annotate a + single field or parameter. The qualifiers are bold in the following example: + + 

+   public class Car {
+     @Inject private @Leather Provider<Seat> seatProvider;
+
+     @Inject void install(@Tinted Windshield windshield,
+         @Big Trunk trunk) { ... }
+   }
+ +

If one injectable method overrides another, the overriding method's + parameters do not automatically inherit qualifiers from the overridden + method's parameters. + +

Injectable Values

+ +

For a given type T and optional qualifier, an injector must be able to + inject a user-specified class that: + +

    +
  1. is assignment compatible with T and
    2. +
  2. has an injectable constructor.
    3. +
+ +

For example, the user might use external configuration to pick an + implementation of T. Beyond that, which values are injected depend upon the + injector implementation and its configuration. + +

Circular Dependencies

+ +

Detecting and resolving circular dependencies is left as an exercise for + the injector implementation. Circular dependencies between two constructors + is an obvious problem, but you can also have a circular dependency between + injectable fields or methods: + + 

+   class A {
+     @Inject B b;
+   }
+   class B {
+     @Inject A a;
+   }
+ +

When constructing an instance of A, a naive injector + implementation might go into an infinite loop constructing an instance of + B to set on A, a second instance of A to set on + B, a second instance of B to set on the second instance of + A, and so on. + +

A conservative injector might detect the circular dependency at build + time and generate an error, at which point the programmer could break the + circular dependency by injecting Provider<A> or Provider<B> instead of A or B respectively. Calling get() on the provider directly from the constructor or + method it was injected into defeats the provider's ability to break up + circular dependencies. In the case of method or field injection, scoping + one of the dependencies (using singleton scope, for + example) may also enable a valid circular relationship. +

+ +

+

+
See Also:
@Qualifier, +Provider
+ +

+ +

+ +

+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/Named.html b/javadoc/javax/inject/Named.html new file mode 100644 index 0000000..fdb018e --- /dev/null +++ b/javadoc/javax/inject/Named.html @@ -0,0 +1,210 @@ + + + + + + +Named + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+ +

+ +javax.inject +
+Annotation Type Named

+
+
+
@Qualifier
+@Documented
+@Retention(value=RUNTIME)
+public @interface Named
+ + +

+String-based qualifier. + +

Example usage: + + 

+   public class Car {
+     @Inject @Named("driver") Seat driverSeat;
+     @Inject @Named("passenger") Seat passengerSeat;
+     ...
+   }
+

+ +

+

+ +

+ + + + + + + + + + + +
+Optional Element Summary
+ java.lang.Stringvalue + +
+          The name.
+  +

+

+value

+
+public abstract java.lang.String value
+
+
The name. +

+

+
+
+
+
+
+
Default:
""
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/Provider.html b/javadoc/javax/inject/Provider.html new file mode 100644 index 0000000..12b3f40 --- /dev/null +++ b/javadoc/javax/inject/Provider.html @@ -0,0 +1,234 @@ + + + + + + +Provider + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ +

+ +javax.inject +
+Interface Provider<T>

+
+
+
public interface Provider<T>
+ + +

+Provides instances of T. Typically implemented by an injector. For + any type T that can be injected, you can also inject + Provider<T>. Compared to injecting T directly, injecting + Provider<T> enables: + +

+ +

For example: + + 

+   class Car {
+     @Inject Car(Provider<Seat> seatProvider) {
+       Seat driver = seatProvider.get();
+       Seat passenger = seatProvider.get();
+       ...
+     }
+   }
+

+ +

+

+ +

+ + + + + + + + + + + + +
+Method Summary
+ Tget() + +
+          Provides a fully-constructed and injected instance of T.
+  +

+ + + + + + + + +
+Method Detail
+ +

+get

+
+T get()
+
+
Provides a fully-constructed and injected instance of T. +

+

+ +
Throws: +
java.lang.RuntimeException - if the injector encounters an error while + providing an instance. For example, if an injectable member on + T throws an exception, the injector may wrap the exception + and throw it to the caller of get(). Callers should not try + to handle such exceptions as the behavior may vary across injector + implementations and even different configurations of the same injector.
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/Qualifier.html b/javadoc/javax/inject/Qualifier.html new file mode 100644 index 0000000..465959c --- /dev/null +++ b/javadoc/javax/inject/Qualifier.html @@ -0,0 +1,194 @@ + + + + + + +Qualifier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+ +

+ +javax.inject +
+Annotation Type Qualifier

+
+
+
@Target(value=ANNOTATION_TYPE)
+@Retention(value=RUNTIME)
+@Documented
+public @interface Qualifier
+ + +

+Identifies qualifier annotations. Anyone can define a new qualifier. A + qualifier annotation: + +

+ +

For example: + + 

+   @java.lang.annotation.Documented
+   @java.lang.annotation.Retention(RUNTIME)
+   @javax.inject.Qualifier
+   public @interface Leather {
+     Color color() default Color.TAN;
+     public enum Color { RED, BLACK, TAN }
+   }
+

+ +

+

+
See Also:
@Named
+ +

+ +

+ +

+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/Scope.html b/javadoc/javax/inject/Scope.html new file mode 100644 index 0000000..4919bc8 --- /dev/null +++ b/javadoc/javax/inject/Scope.html @@ -0,0 +1,215 @@ + + + + + + +Scope + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+ +

+ +javax.inject +
+Annotation Type Scope

+
+
+
@Target(value=ANNOTATION_TYPE)
+@Retention(value=RUNTIME)
+@Documented
+public @interface Scope
+ + +

+Identifies scope annotations. A scope annotation applies to a class + containing an injectable constructor and governs how the injector reuses + instances of the type. By default, if no scope annotation is present, the + injector creates an instance (by injecting the type's constructor), uses + the instance for one injection, and then forgets it. If a scope annotation + is present, the injector may retain the instance for possible reuse in a + later injection. If multiple threads can access a scoped instance, its + implementation should be thread safe. The implementation of the scope + itself is left up to the injector. + +

In the following example, the scope annotation @Singleton ensures + that we only have one Log instance: + + 

+   @Singleton
+   class Log {
+     void log(String message) { ... }
+   }
+ +

The injector generates an error if it encounters more than one scope + annotation on the same class or a scope annotation it doesn't support. + +

A scope annotation: +

+ +

For example: + + 

+   @java.lang.annotation.Documented
+   @java.lang.annotation.Retention(RUNTIME)
+   @javax.inject.Scope
+   public @interface RequestScoped {}
+ +

Annotating scope annotations with @Scope helps the injector + detect the case where a programmer used the scope annotation on a class but + forgot to configure the scope in the injector. A conservative injector + would generate an error rather than not apply a scope. +

+ +

+

+
See Also:
@Singleton
+ +

+ +

+ +

+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/Singleton.html b/javadoc/javax/inject/Singleton.html new file mode 100644 index 0000000..12f9ea6 --- /dev/null +++ b/javadoc/javax/inject/Singleton.html @@ -0,0 +1,169 @@ + + + + + + +Singleton + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+ +

+ +javax.inject +
+Annotation Type Singleton

+
+
+
@Scope
+@Documented
+@Retention(value=RUNTIME)
+public @interface Singleton
+ + +

+Identifies a type that the injector only instantiates once. Not inherited. +

+ +

+

+
See Also:
@Scope
+ +

+ +

+ +

+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package   Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + + +
+ SUMMARY: REQUIRED | OPTIONAL +DETAIL: ELEMENT
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/package-frame.html b/javadoc/javax/inject/package-frame.html new file mode 100644 index 0000000..bef990f --- /dev/null +++ b/javadoc/javax/inject/package-frame.html @@ -0,0 +1,51 @@ + + + + + + +javax.inject + + + + + + + + + + + +javax.inject + + + + +
+Interfaces  + +
+Provider
+ + + + + + +
+Annotation Types  + +
+Inject +
+Named +
+Qualifier +
+Scope +
+Singleton
+ + + + diff --git a/javadoc/javax/inject/package-summary.html b/javadoc/javax/inject/package-summary.html new file mode 100644 index 0000000..a1dd828 --- /dev/null +++ b/javadoc/javax/inject/package-summary.html @@ -0,0 +1,332 @@ + + + + + + +javax.inject + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV PACKAGE  + NEXT PACKAGE + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+

+Package javax.inject +

+This package specifies a means for obtaining objects in such a way as to + maximize reusability, testability and maintainability compared to + traditional approaches such as constructors, factories, and service + locators (e.g., JNDI). This process, known as dependency + injection, is beneficial to most nontrivial applications. +

+See: +
+          Description +

+ + + + + + + + + +
+Interface Summary
Provider<T>Provides instances of T.
+  + +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
+Annotation Types Summary
InjectIdentifies injectable constructors, methods, and fields.
NamedString-based qualifier.
QualifierIdentifies qualifier annotations.
ScopeIdentifies scope annotations.
SingletonIdentifies a type that the injector only instantiates once.
+  + +

+

+Package javax.inject Description +

+ +

+This package specifies a means for obtaining objects in such a way as to + maximize reusability, testability and maintainability compared to + traditional approaches such as constructors, factories, and service + locators (e.g., JNDI). This process, known as dependency + injection, is beneficial to most nontrivial applications. + +

Many types depend on other types. For example, a Stopwatch might + depend on a TimeSource. The types on which a type depends are + known as its dependencies. The process of finding an instance of a + dependency to use at run time is known as resolving the dependency. + If no such instance can be found, the dependency is said to be + unsatisfied, and the application is broken. + +

In the absence of dependency injection, an object can resolve its + dependencies in a few ways. It can invoke a constructor, hard-wiring an + object directly to its dependency's implementation and life cycle: + + 

   class Stopwatch {
+     final TimeSource timeSource;
+     Stopwatch () {
+       timeSource = new AtomicClock(...);
+     }
+     void start() { ... }
+     long stop() { ... }
+   }
+ +

If more flexibility is needed, the object can call out to a factory or + service locator: + + 

   class Stopwatch {
+     final TimeSource timeSource;
+     Stopwatch () {
+       timeSource = DefaultTimeSource.getInstance();
+     }
+     void start() { ... }
+     long stop() { ... }
+   }
+ +

In deciding between these traditional approaches to dependency + resolution, a programmer must make trade-offs. Constructors are more + concise but restrictive. Factories decouple the client and implementation + to some extent but require boilerplate code. Service locators decouple even + further but reduce compile time type safety. All three approaches inhibit + unit testing. For example, if the programmer uses a factory, each test + against code that depends on the factory will have to mock out the factory + and remember to clean up after itself or else risk side effects: + + 

   void testStopwatch() {
+     TimeSource original = DefaultTimeSource.getInstance();
+     DefaultTimeSource.setInstance(new MockTimeSource());
+     try {
+       // Now, we can actually test Stopwatch.
+       Stopwatch sw = new Stopwatch();
+       ...
+     } finally {
+       DefaultTimeSource.setInstance(original);
+     }
+   }
+ +

In practice, supporting this ability to mock out a factory results in + even more boilerplate code. Tests that mock out and clean up after multiple + dependencies quickly get out of hand. To make matters worse, a programmer + must predict accurately how much flexibility will be needed in the future + or else suffer the consequences. If a programmer initially elects to use a + constructor but later decides that more flexibility is required, the + programmer must replace every call to the constructor. If the programmer + errs on the side of caution and write factories up front, it may result in + a lot of unnecessary boilerplate code, adding noise, complexity, and + error-proneness. + +

Dependency injection addresses all of these issues. Instead of + the programmer calling a constructor or factory, a tool called a + dependency injector passes dependencies to objects: + + 

   class Stopwatch {
+     final TimeSource timeSource;
+     @Inject Stopwatch(TimeSource TimeSource) {
+       this.TimeSource = TimeSource;
+     }
+     void start() { ... }
+     long stop() { ... }
+   }
+ +

The injector further passes dependencies to other dependencies until it + constructs the entire object graph. For example, suppose the programmer + asked an injector to create a StopwatchWidget instance: + + 

   /** GUI for a Stopwatch */
+   class StopwatchWidget {
+     @Inject StopwatchWidget(Stopwatch sw) { ... }
+     ...
+   }
+ +

The injector might: +

    +
  1. Find a TimeSource +
  2. Construct a Stopwatch with the TimeSource +
  3. Construct a StopwatchWidget with the Stopwatch +
+ +

This leaves the programmer's code clean, flexible, and relatively free + of dependency-related infrastructure. + +

In unit tests, the programmer can now construct objects directly + (without an injector) and pass in mock dependencies. The programmer no + longer needs to set up and tear down factories or service locators in each + test. This greatly simplifies our unit test: + + 

   void testStopwatch() {
+     Stopwatch sw = new Stopwatch(new MockTimeSource());
+     ...
+   }
+ +

The total decrease in unit-test complexity is proportional to the + product of the number of unit tests and the number of dependencies. + +

This package provides dependency injection annotations that enable + portable classes, but it leaves external dependency configuration up to + the injector implementation. Programmers annotate constructors, methods, + and fields to advertise their injectability (constructor injection is + demonstrated in the examples above). A dependency injector identifies a + class's dependencies by inspecting these annotations, and injects the + dependencies at run time. Moreover, the injector can verify that all + dependencies have been satisfied at build time. A service locator, + by contrast, cannot detect unsatisfied dependencies until run time. + +

Injector implementations can take many forms. An injector could + configure itself using XML, annotations, a DSL (domain-specific language), + or even plain Java code. An injector could rely on reflection or code + generation. An injector that uses compile-time code generation may not even + have its own run time representation. Other injectors may not be able to + generate code at all, neither at compile nor run time. A "container", for + some definition, can be an injector, but this package specification aims to + minimize restrictions on injector implementations. +

+ +

+

+
See Also:
@Inject
+
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class  Tree  Deprecated  Index  Help 
+		 + +
+ PREV PACKAGE  + NEXT PACKAGE + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/javax/inject/package-tree.html b/javadoc/javax/inject/package-tree.html new file mode 100644 index 0000000..4c0e056 --- /dev/null +++ b/javadoc/javax/inject/package-tree.html @@ -0,0 +1,150 @@ + + + + + + +javax.inject Class Hierarchy + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Hierarchy For Package javax.inject +

+
+

+Interface Hierarchy +

+ +

+Annotation Type Hierarchy +

+ +
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/overview-tree.html b/javadoc/overview-tree.html new file mode 100644 index 0000000..46726cf --- /dev/null +++ b/javadoc/overview-tree.html @@ -0,0 +1,152 @@ + + + + + + +Class Hierarchy + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+
+

+Hierarchy For All Packages

+
+
+
Package Hierarchies:
javax.inject
+
+

+Interface Hierarchy +

+ +

+Annotation Type Hierarchy +

+ +
+ + + + + + + + + + + + + + + +
+ + + + + + + + + + +
Package  Class   Tree  Deprecated  Index  Help 
+		 + +
+ PREV  + NEXT + FRAMES   + NO FRAMES   +  + + + +
+ + + +
+Copyright (C) 2009 The JSR-330 Expert Group. Licensed under the Apache License, Version 2.0. + + diff --git a/javadoc/package-list b/javadoc/package-list new file mode 100644 index 0000000..98a4cde --- /dev/null +++ b/javadoc/package-list @@ -0,0 +1 @@ +javax.inject diff --git a/javadoc/resources/inherit.gif b/javadoc/resources/inherit.gif new file mode 100644 index 0000000..c814867 Binary files /dev/null and b/javadoc/resources/inherit.gif differ diff --git a/javadoc/stylesheet.css b/javadoc/stylesheet.css new file mode 100644 index 0000000..6d31fdb --- /dev/null +++ b/javadoc/stylesheet.css @@ -0,0 +1,29 @@ +/* Javadoc style sheet */ + +/* Define colors, fonts and other style attributes here to override the defaults */ + +/* Page background color */ +body { background-color: #FFFFFF } + +/* Headings */ +h1 { font-size: 145% } + +/* Table colors */ +.TableHeadingColor { background: #CCCCFF } /* Dark mauve */ +.TableSubHeadingColor { background: #EEEEFF } /* Light mauve */ +.TableRowColor { background: #FFFFFF } /* White */ + +/* Font used in left-hand frame lists */ +.FrameTitleFont { font-size: 100%; font-family: Helvetica, Arial, sans-serif } +.FrameHeadingFont { font-size: 90%; font-family: Helvetica, Arial, sans-serif } +.FrameItemFont { font-size: 90%; font-family: Helvetica, Arial, sans-serif } + +/* Navigation bar fonts and colors */ +.NavBarCell1 { background-color:#EEEEFF;} /* Light mauve */ +.NavBarCell1Rev { background-color:#00008B;} /* Dark Blue */ +.NavBarFont1 { font-family: Arial, Helvetica, sans-serif; color:#000000;} +.NavBarFont1Rev { font-family: Arial, Helvetica, sans-serif; color:#FFFFFF;} + +.NavBarCell2 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;} +.NavBarCell3 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;} + -- cgit v1.2.3