464727 - Update Javadoc for Java 8 DocLint

+ Fixing javadoc in jetty-plus
This commit is contained in:
Joakim Erdfelt 2015-04-22 09:28:24 -07:00
parent eb7de5eaee
commit b58bbd906d
13 changed files with 135 additions and 145 deletions

View File

@ -91,7 +91,7 @@ public class ContainerInitializer
/**
* A class has been found that has an annotation of interest
* to this initializer.
* @param className
* @param className the class name to add
*/
public void addAnnotatedTypeName (String className)
{

View File

@ -32,11 +32,10 @@ import org.eclipse.jetty.util.log.Logger;
/**
* Injection
*
* <p>
* Represents the injection of a resource into a target (method or field).
* The injection is performed by doing an ENC lookup using the jndi
* name provided, and setting the object obtained on the target.
*
*/
public class Injection
{
@ -168,7 +167,7 @@ public class Injection
/**
* Inject a value for a Resource from JNDI into an object
* @param injectable
* @param injectable the object to inject
*/
public void inject (Object injectable)
{
@ -187,7 +186,7 @@ public class Injection
/**
* The Resource must already exist in the ENC of this webapp.
* @return the injected valud
* @throws NamingException
* @throws NamingException if unable to lookup value
*/
public Object lookupInjectedValue ()
throws NamingException
@ -200,8 +199,8 @@ public class Injection
/**
* Inject value from jndi into a field of an instance
* @param field
* @param injectable
* @param field the field to inject into
* @param injectable the value to inject
*/
protected void injectField (Field field, Object injectable)
{
@ -221,8 +220,8 @@ public class Injection
/**
* Inject value from jndi into a setter method of an instance
* @param method
* @param injectable
* @param method the method to inject into
* @param injectable the value to inject
*/
protected void injectMethod (Method method, Object injectable)
{

View File

@ -25,6 +25,9 @@ import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
@ -46,7 +49,7 @@ public class LifeCycleCallbackCollection
/**
* Add a Callback to the list of callbacks.
*
* @param callback
* @param callback the callback
*/
public void add (LifeCycleCallback callback)
{
@ -95,10 +98,10 @@ public class LifeCycleCallbackCollection
}
/**
* Call the method, if one exists, that is annotated with PostConstruct
* or with &lt;post-construct&gt; in web.xml
* Call the method, if one exists, that is annotated with {@link PostConstruct}
* or with <code>&lt;post-construct&gt;</code> in web.xml
* @param o the object on which to attempt the callback
* @throws Exception
* @throws Exception if unable to call {@link PostConstructCallback}
*/
public void callPostConstructCallback (Object o)
throws Exception
@ -120,9 +123,10 @@ public class LifeCycleCallbackCollection
/**
* Call the method, if one exists, that is annotated with PreDestroy
* or with &lt;pre-destroy&gt; in web.xml
* Call the method, if one exists, that is annotated with {@link PreDestroy}
* or with <code>&lt;pre-destroy&gt;</code> in web.xml
* @param o the object on which to attempt the callback
* @throws Exception if unable to call {@link PreDestroyCallback}
*/
public void callPreDestroyCallback (Object o)
throws Exception
@ -141,7 +145,7 @@ public class LifeCycleCallbackCollection
/**
* Generate a read-only view of the post-construct callbacks
* @return
* @return the map of {@link PostConstructCallback}s
*/
public Map<String, List<LifeCycleCallback>> getPostConstructCallbackMap()
{
@ -150,7 +154,7 @@ public class LifeCycleCallbackCollection
/**
* Generate a read-only view of the pre-destroy callbacks
* @return
* @return the map of {@link PreDestroyCallback}s
*/
public Map<String, List<LifeCycleCallback>> getPreDestroyCallbackMap()
{
@ -159,7 +163,7 @@ public class LifeCycleCallbackCollection
/**
* Amalgamate all post-construct callbacks and return a read only list
* @return
* @return the collection of {@link PostConstructCallback}s
*/
public Collection<LifeCycleCallback> getPostConstructCallbacks()
{
@ -173,7 +177,7 @@ public class LifeCycleCallbackCollection
/**
* Amalgamate all pre-destroy callbacks and return a read only list
* @return
* @return the collection of {@link PreDestroyCallback}s
*/
public Collection<LifeCycleCallback> getPreDestroyCallbacks()
{

View File

@ -23,7 +23,7 @@ import org.eclipse.jetty.servlet.ServletHolder;
/**
* RunAs
* <p>
* Represents a &lt;run-as&gt; element in web.xml, or a runAs annotation.
* Represents a <code>&lt;run-as&gt;</code> element in web.xml, or a <code>&#064;RunAs</code> annotation.
*/
public class RunAs
{
@ -54,10 +54,6 @@ public class RunAs
return _roleName;
}
/**
* @param holder
*/
public void setRunAs (ServletHolder holder)
{
if (holder == null)
@ -70,6 +66,5 @@ public class RunAs
if (holder.getRegistration().getRunAsRole() == null)
holder.getRegistration().setRunAsRole(_roleName);
}
}
}

View File

@ -24,8 +24,6 @@ import javax.naming.NamingException;
/**
* EnvEntry
*
*
*/
public class EnvEntry extends NamingEntry
{

View File

@ -28,15 +28,13 @@ import javax.naming.NamingException;
import org.eclipse.jetty.jndi.NamingUtil;
import org.eclipse.jetty.util.log.Logger;
/**
* NamingEntry
*
* <p>
* Base class for all jndi related entities. Instances of
* subclasses of this class are declared in jetty.xml or in a
* webapp's WEB-INF/jetty-env.xml file.
*
* <p>
* NOTE: that all NamingEntries will be bound in a single namespace.
* The "global" level is just in the top level context. The "local"
* level is a context specific to a webapp.
@ -73,7 +71,7 @@ public abstract class NamingEntry
* be linked to the webapp's env-entry, resource-ref etc entries.
*
* @param jndiName the name of the object which will eventually be in java:comp/env
* @throws NamingException
* @throws NamingException if unable to create naming entry
*/
protected NamingEntry (String jndiName)
throws NamingException
@ -85,14 +83,15 @@ public abstract class NamingEntry
/**
* Add a java:comp/env binding for the object represented by this NamingEntry,
* Add a <code>java:comp/env</code> binding for the object represented by this NamingEntry,
* but bind it as the name supplied
* @throws NamingException
* @param localName the local name to bind
* @throws NamingException if unable to bind
*/
public void bindToENC(String localName)
throws NamingException
{
//TODO - check on the whole overriding/non-overriding thing
// TODO - check on the whole overriding/non-overriding thing
InitialContext ic = new InitialContext();
Context env = (Context)ic.lookup("java:comp/env");
__log.debug("Binding java:comp/env/"+localName+" to "+_objectNameString);
@ -160,22 +159,24 @@ public abstract class NamingEntry
/**
* Save the NamingEntry for later use.
*
* <p>
* Saving is done by binding the NamingEntry
* itself, and the value it represents into
* JNDI. In this way, we can link to the
* value it represents later, but also
* still retrieve the NamingEntry itself too.
*
* <p>
* The object is bound at the jndiName passed in.
* This NamingEntry is bound at __/jndiName.
*
* <p>
* eg
*
* <pre>
* jdbc/foo : DataSource
* __/jdbc/foo : NamingEntry
* </pre>
*
* @throws NamingException
* @param object the object to save
* @throws NamingException if unable to save
*/
protected void save (Object object)
throws NamingException

View File

@ -48,7 +48,8 @@ public class NamingEntryUtil
* @param scope the scope of the lookup
* @param asName the name to bind as
* @param mappedName the name from the environment to link to asName
* @throws NamingException
* @return true if bind success, false if not bound
* @throws NamingException if unable to bind
*/
public static boolean bindToENC (Object scope, String asName, String mappedName)
throws NamingException
@ -74,10 +75,10 @@ public class NamingEntryUtil
/**
* Find a NamingEntry in the given scope.
*
* @param scope
* @param jndiName
* @param scope the object scope
* @param jndiName the jndi name
* @return the naming entry for the given scope
* @throws NamingException
* @throws NamingException if unable to lookup naming entry
*/
public static NamingEntry lookupNamingEntry (Object scope, String jndiName)
throws NamingException
@ -112,10 +113,10 @@ public class NamingEntryUtil
* Get all NameEntries of a certain type in the given naming
* environment scope (server-wide names or context-specific names)
*
* @param scope
* @param scope the object scope
* @param clazz the type of the entry
* @return all NameEntries of a certain type in the given naming environment scope (server-wide names or context-specific names)
* @throws NamingException
* @throws NamingException if unable to lookup the naming entries
*/
public static List<Object> lookupNamingEntries (Object scope, Class<?> clazz)
throws NamingException

View File

@ -18,19 +18,13 @@
package org.eclipse.jetty.plus.jndi;
import javax.naming.NamingException;
/**
* Resource
*
*
*/
public class Resource extends NamingEntry
{
public Resource (Object scope, String jndiName, Object objToBind)
throws NamingException
{
@ -38,15 +32,10 @@ public class Resource extends NamingEntry
save(objToBind);
}
/**
* @param jndiName
* @param objToBind
*/
public Resource (String jndiName, Object objToBind)
throws NamingException
{
super(jndiName);
save(objToBind);
}
}

View File

@ -46,9 +46,8 @@ import org.eclipse.jetty.util.security.Credential;
/**
*
* DataSourceUserRealm
*
* <p>
* Obtain user/password/role information from a database
* via jndi DataSource.
*/
@ -289,7 +288,7 @@ public class DataSourceLoginService extends MappedLoginService
/* ------------------------------------------------------------ */
/** Load user's info from database.
*
* @param userName
* @param userName the user name
*/
@Override
protected UserIdentity loadUser (String userName)
@ -356,7 +355,8 @@ public class DataSourceLoginService extends MappedLoginService
* necessary sql query strings based on the configured table
* and column names.
*
* @throws NamingException
* @throws NamingException if unable to init jndi
* @throws SQLException if unable to init database
*/
public void initDb() throws NamingException, SQLException
{
@ -367,9 +367,9 @@ public class DataSourceLoginService extends MappedLoginService
InitialContext ic = new InitialContext();
assert ic!=null;
//TODO Should we try webapp scope too?
// TODO Should we try webapp scope too?
//try finding the datasource in the Server scope
// try finding the datasource in the Server scope
if (_server != null)
{
try

View File

@ -40,14 +40,13 @@ import org.eclipse.jetty.plus.jndi.NamingEntryUtil;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
import org.eclipse.jetty.webapp.AbstractConfiguration;
import org.eclipse.jetty.webapp.Configuration;
import org.eclipse.jetty.webapp.WebAppContext;
import org.eclipse.jetty.xml.XmlConfiguration;
/**
* EnvConfiguration
*
*
*/
public class EnvConfiguration extends AbstractConfiguration
{
@ -61,10 +60,6 @@ public class EnvConfiguration extends AbstractConfiguration
this.jettyEnvXmlUrl = url;
}
/**
* @see Configuration#configure(WebAppContext)
* @throws Exception
*/
@Override
public void preConfigure (WebAppContext context) throws Exception
{
@ -72,9 +67,6 @@ public class EnvConfiguration extends AbstractConfiguration
createEnvContext(context);
}
/**
* @throws Exception
*/
@Override
public void configure (WebAppContext context) throws Exception
{
@ -138,8 +130,7 @@ public class EnvConfiguration extends AbstractConfiguration
/**
* Remove jndi setup from start
* @see Configuration#deconfigure(WebAppContext)
* @throws Exception
* @throws Exception if unable to deconfigure
*/
@Override
public void deconfigure (WebAppContext context) throws Exception
@ -179,8 +170,7 @@ public class EnvConfiguration extends AbstractConfiguration
/**
* Remove all jndi setup
* @see Configuration#deconfigure(WebAppContext)
* @throws Exception
* @throws Exception if unable to destroy
*/
@Override
public void destroy (WebAppContext context) throws Exception
@ -207,7 +197,8 @@ public class EnvConfiguration extends AbstractConfiguration
* web.xml file can potentially override them.
*
* We first bind EnvEntries declared in Server scope, then WebAppContext scope.
* @throws NamingException
* @param context the context to use for the object scope
* @throws NamingException if unable to bind env entries
*/
public void bindEnvEntries (WebAppContext context)
throws NamingException

View File

@ -48,10 +48,7 @@ import org.eclipse.jetty.xml.XmlParser;
/**
* PlusDescriptorProcessor
*
*
*/
public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
{
private static final Logger LOG = Log.getLogger(PlusDescriptorProcessor.class);
@ -109,14 +106,13 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
{
}
/**
* JavaEE 5.4.1.3
*
* @param node
* @throws Exception
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
* @throws Exception if unable to process jndi bindings
*/
public void visitEnvEntry (WebAppContext context, Descriptor descriptor, XmlParser.Node node)
throws Exception
@ -188,18 +184,20 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* Common Annotations Spec section 2.3:
* <p>
* resource-ref is for:
* - javax.sql.DataSource
* - javax.jms.ConnectionFactory
* - javax.jms.QueueConnectionFactory
* - javax.jms.TopicConnectionFactory
* - javax.mail.Session
* - java.net.URL
* - javax.resource.cci.ConnectionFactory
* - org.omg.CORBA_2_3.ORB
* - any other connection factory defined by a resource adapter
* <ul>
* <li>javax.sql.DataSource</li>
* <li>javax.jms.ConnectionFactory</li>
* <li>javax.jms.QueueConnectionFactory</li>
* <li>javax.jms.TopicConnectionFactory</li>
* <li>javax.mail.Session</li>
* <li>java.net.URL</li>
* <li>javax.resource.cci.ConnectionFactory</li>
* <li>org.omg.CORBA_2_3.ORB</li>
* <li>any other connection factory defined by a resource adapter</li>
* </ul>
*
* TODO
* If web.xml contains a resource-ref with injection targets, all resource-ref entries
* of the same name are ignored in web fragments. If web.xml does not contain any
* injection-targets, then they are merged from all the fragments.
@ -211,8 +209,10 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
* a real resource in the environment. At the moment, we insist that the
* jetty.xml file name of the resource has to be exactly the same as the
* name in web.xml deployment descriptor, but it shouldn't have to be
*
*
* <p>
* Maintenance update 3.0a to spec:
* <p>
* Update Section 8.2.3.h.ii with the following - If a resource reference
* element is specified in two fragments, while absent from the main web.xml,
* and all the attributes and child elements of the resource reference element
@ -220,13 +220,15 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
* It is considered an error if a resource reference element has the same name
* specified in two fragments, while absent from the main web.xml and the attributes
* and child elements are not identical in the two fragments. For example, if two
* web fragments declare a <resource-ref> with the same <resource-ref-name> element
* web fragments declare a <code>&lt;resource-ref&gt;</code> with the same <code>&lt;resource-ref-name&gt;</code> element
* but the type in one is specified as javax.sql.DataSource while the type in the
* other is that of a java mail resource, then an error must be reported and the
* application MUST fail to deploy.
*
* @param node
* @throws Exception
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
* @throws Exception if unable to bind nodes, or load classes
*/
public void visitResourceRef (WebAppContext context, Descriptor descriptor, XmlParser.Node node)
throws Exception
@ -338,13 +340,18 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* Common Annotations Spec section 2.3:
* resource-env-ref is for:
* - javax.transaction.UserTransaction
* - javax.resource.cci.InteractionSpec
* - anything else that is not a connection factory
*
* @param node
* @throws Exception
* <p>
* resource-env-ref is for:
* <ul>
* <li>javax.transaction.UserTransaction</li>
* <li>javax.resource.cci.InteractionSpec</li>
* <li>anything else that is not a connection factory</li>
* </ul>
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
* @throws Exception if unable to load classes, or bind jndi entries
*/
public void visitResourceEnvRef (WebAppContext context, Descriptor descriptor, XmlParser.Node node)
throws Exception
@ -438,11 +445,17 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* Common Annotations Spec section 2.3:
* message-destination-ref is for:
* - javax.jms.Queue
* - javax.jms.Topic
* @param node
* @throws Exception
* <p>
* message-destination-ref is for:
* <ul>
* <li>javax.jms.Queue</li>
* <li>javax.jms.Topic</li>
* </ul>
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
* @throws Exception if unable to load classes or bind jndi entries
*/
public void visitMessageDestinationRef (WebAppContext context, Descriptor descriptor, XmlParser.Node node)
throws Exception
@ -536,7 +549,10 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
* are ignored. Otherwise, post-constructs from fragments are merged.
* post-construct is the name of a class and method to call after all
* resources have been setup but before the class is put into use
* @param node
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
*/
public void visitPostConstruct(WebAppContext context, Descriptor descriptor, XmlParser.Node node)
{
@ -624,7 +640,10 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
*
* pre-destroy is the name of a class and method to call just as
* the instance is being destroyed
* @param node
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
*/
public void visitPreDestroy(WebAppContext context, Descriptor descriptor, XmlParser.Node node)
{
@ -705,12 +724,13 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* Iterate over the &lt;injection-target&gt; entries for a node
*
* @param descriptor
* @param node
* @param jndiName
* @param valueClass
* Iterate over the <code>&lt;injection-target&gt;</code> entries for a node
*
* @param context the context
* @param descriptor the descriptor
* @param node the xml node
* @param jndiName the jndi name
* @param valueClass the value class
*/
public void addInjections (WebAppContext context, Descriptor descriptor, XmlParser.Node node, String jndiName, Class<?> valueClass)
{
@ -763,9 +783,9 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* @param name
* @param value
* @throws Exception
* @param name the jndi name
* @param value the value
* @throws Exception if unable to bind entry
*/
public void bindEnvEntry(String name, Object value) throws Exception
{
@ -799,12 +819,14 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
/**
* Bind a resource reference.
*
* <p>
* If a resource reference with the same name is in a jetty-env.xml
* file, it will already have been bound.
*
* @param name
* @throws Exception
*
* @param context the context
* @param name the jndi name
* @param typeClass the type class
* @throws Exception if unable to bind resource
*/
public void bindResourceRef(WebAppContext context, String name, Class<?> typeClass)
throws Exception
@ -812,10 +834,6 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
bindEntry(context, name, typeClass);
}
/**
* @param name
* @throws Exception
*/
public void bindResourceEnvRef(WebAppContext context, String name, Class<?> typeClass)
throws Exception
{
@ -834,16 +852,17 @@ public class PlusDescriptorProcessor extends IterativeDescriptorProcessor
* Bind a resource with the given name from web.xml of the given type
* with a jndi resource from either the server or the webapp's naming
* environment.
*
* <p>
* As the servlet spec does not cover the mapping of names in web.xml with
* names from the execution environment, jetty uses the concept of a Link, which is
* a subclass of the NamingEntry class. A Link defines a mapping of a name
* from web.xml with a name from the execution environment (ie either the server or the
* webapp's naming environment).
*
*
* @param context the context
* @param name name of the resource from web.xml
* @param typeClass
* @throws Exception
* @param typeClass the type class
* @throws Exception the exception
*/
protected void bindEntry (WebAppContext context, String name, Class<?> typeClass)
throws Exception

View File

@ -44,9 +44,6 @@ import org.junit.After;
import org.junit.Before;
import org.junit.Test;
/**
*
*/
public class TestNamingEntries
{
public class ScopeA
@ -145,7 +142,7 @@ public class TestNamingEntries
* after each test we should scrape out any lingering bindings to prevent cross test pollution
* as observed when running java 7
*
* @throws Exception
* @throws Exception on test failure
*/
@After
public void after() throws Exception

View File

@ -42,8 +42,6 @@ import org.junit.Test;
/**
* PlusDescriptorProcessorTest
*
*
*/
public class PlusDescriptorProcessorTest
{
@ -53,9 +51,7 @@ public class PlusDescriptorProcessorTest
protected FragmentDescriptor fragDescriptor3;
protected FragmentDescriptor fragDescriptor4;
protected WebAppContext context;
/**
* @throws java.lang.Exception
*/
@Before
public void setUp() throws Exception
{