From fcb44dca7cc80d199837e31de4b8228192b5960e Mon Sep 17 00:00:00 2001 From: darcy Date: Tue, 6 Aug 2013 16:01:39 -0700 Subject: [PATCH] 8022406: Fix doclint issues in java.beans Reviewed-by: prr --- .../classes/java/beans/AppletInitializer.java | 3 +- src/share/classes/java/beans/Beans.java | 9 ++-- .../java/beans/ConstructorProperties.java | 4 +- .../beans/DefaultPersistenceDelegate.java | 3 +- .../classes/java/beans/EventHandler.java | 5 ++- src/share/classes/java/beans/Expression.java | 6 ++- .../java/beans/IndexedPropertyDescriptor.java | 4 ++ .../classes/java/beans/Introspector.java | 13 +++++- .../java/beans/PersistenceDelegate.java | 3 +- .../java/beans/PropertyChangeSupport.java | 6 +-- .../java/beans/PropertyDescriptor.java | 2 + src/share/classes/java/beans/Transient.java | 12 ++++-- .../java/beans/VetoableChangeSupport.java | 10 ++--- .../java/beans/beancontext/BeanContext.java | 14 +++--- .../beans/beancontext/BeanContextChild.java | 4 +- .../beancontext/BeanContextChildSupport.java | 6 ++- .../BeanContextMembershipEvent.java | 3 +- .../beancontext/BeanContextServices.java | 5 ++- .../BeanContextServicesSupport.java | 27 ++++++++++-- .../beans/beancontext/BeanContextSupport.java | 43 ++++++++++++++----- 20 files changed, 130 insertions(+), 52 deletions(-) diff --git a/src/share/classes/java/beans/AppletInitializer.java b/src/share/classes/java/beans/AppletInitializer.java index 9e4b7239d..2c271a236 100644 --- a/src/share/classes/java/beans/AppletInitializer.java +++ b/src/share/classes/java/beans/AppletInitializer.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2000, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -68,7 +68,6 @@ public interface AppletInitializer { * the Applet with its Container during the subsequent invocation of its * addChildren() method. * - *

* * @param newAppletBean The newly instantiated JavaBean * @param bCtxt The BeanContext intended for this Applet, or diff --git a/src/share/classes/java/beans/Beans.java b/src/share/classes/java/beans/Beans.java index 2183d2241..58a411691 100644 --- a/src/share/classes/java/beans/Beans.java +++ b/src/share/classes/java/beans/Beans.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -62,7 +62,7 @@ public class Beans { *

* Instantiate a JavaBean. *

- * + * @return a JavaBean * @param cls the class-loader from which we should create * the bean. If this is null, then the system * class-loader is used. @@ -82,6 +82,7 @@ public class Beans { *

* Instantiate a JavaBean. *

+ * @return a JavaBean * * @param cls the class-loader from which we should create * the bean. If this is null, then the system @@ -137,6 +138,7 @@ public class Beans { * the JDK appletviewer (for a reference browser environment) and the * BDK BeanBox (for a reference bean container). * + * @return a JavaBean * @param cls the class-loader from which we should create * the bean. If this is null, then the system * class-loader is used. @@ -361,6 +363,8 @@ public class Beans { * This method is provided in Beans 1.0 as a hook to allow the * addition of more flexible bean behaviour in the future. * + * @return an object representing a specified type view of the + * source object * @param bean Object from which we want to obtain a view. * @param targetType The type of view we'd like to get. * @@ -384,7 +388,6 @@ public class Beans { return Introspector.isSubclass(bean.getClass(), targetType); } - /** * Test if we are in design-mode. * diff --git a/src/share/classes/java/beans/ConstructorProperties.java b/src/share/classes/java/beans/ConstructorProperties.java index 3166de317..5ee947c1f 100644 --- a/src/share/classes/java/beans/ConstructorProperties.java +++ b/src/share/classes/java/beans/ConstructorProperties.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -61,7 +61,7 @@ import static java.lang.annotation.RetentionPolicy.*; the {@code getY()} method. Since parameter names are not in general available at runtime, without the annotation there would be no way to know whether the parameters correspond to {@code getX()} - and {@code getY()} or the other way around.

+ and {@code getY()} or the other way around. @since 1.6 */ diff --git a/src/share/classes/java/beans/DefaultPersistenceDelegate.java b/src/share/classes/java/beans/DefaultPersistenceDelegate.java index 3c6c7c2a3..de6a1b751 100644 --- a/src/share/classes/java/beans/DefaultPersistenceDelegate.java +++ b/src/share/classes/java/beans/DefaultPersistenceDelegate.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -382,6 +382,7 @@ public class DefaultPersistenceDelegate extends PersistenceDelegate { * a class such that no property value depends on the value of * a subsequent property. * + * @param type the type of the instances * @param oldInstance The instance to be copied. * @param newInstance The instance that is to be modified. * @param out The stream to which any initialization statements should be written. diff --git a/src/share/classes/java/beans/EventHandler.java b/src/share/classes/java/beans/EventHandler.java index b7635c931..b428f2892 100644 --- a/src/share/classes/java/beans/EventHandler.java +++ b/src/share/classes/java/beans/EventHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -515,6 +515,7 @@ public class EventHandler implements InvocationHandler { * * * + * @param the type to create * @param listenerInterface the listener interface to create a proxy for * @param target the object that will perform the action * @param action the name of a (possibly qualified) property or method on @@ -570,6 +571,7 @@ public class EventHandler implements InvocationHandler { * * * + * @param the type to create * @param listenerInterface the listener interface to create a proxy for * @param target the object that will perform the action * @param action the name of a (possibly qualified) property or method on @@ -659,6 +661,7 @@ public class EventHandler implements InvocationHandler { * * * + * @param the type to create * @param listenerInterface the listener interface to create a proxy for * @param target the object that will perform the action * @param action the name of a (possibly qualified) property or method on diff --git a/src/share/classes/java/beans/Expression.java b/src/share/classes/java/beans/Expression.java index f7a15c346..ce6fafb10 100644 --- a/src/share/classes/java/beans/Expression.java +++ b/src/share/classes/java/beans/Expression.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -139,7 +139,7 @@ public class Expression extends Statement { * replaces this default value in the same way that any other value * would, ensuring that expressions are never evaluated more than once. *

- * See the excecute method for details on how + * See the execute method for details on how * methods are chosen using the dynamic types of the target * and arguments. * @@ -147,6 +147,8 @@ public class Expression extends Statement { * @see #setValue * * @return The result of applying this method to these arguments. + * @throws Exception if the method with the specified methodName + * throws an exception */ public Object getValue() throws Exception { if (value == unbound) { diff --git a/src/share/classes/java/beans/IndexedPropertyDescriptor.java b/src/share/classes/java/beans/IndexedPropertyDescriptor.java index d3f16d290..1d59f7afd 100644 --- a/src/share/classes/java/beans/IndexedPropertyDescriptor.java +++ b/src/share/classes/java/beans/IndexedPropertyDescriptor.java @@ -207,6 +207,8 @@ public class IndexedPropertyDescriptor extends PropertyDescriptor { * Sets the method that should be used to read an indexed property value. * * @param readMethod The new indexed read method. + * @throws IntrospectionException if an exception occurs during + * introspection. */ public synchronized void setIndexedReadMethod(Method readMethod) throws IntrospectionException { @@ -285,6 +287,8 @@ public class IndexedPropertyDescriptor extends PropertyDescriptor { * Sets the method that should be used to write an indexed property value. * * @param writeMethod The new indexed write method. + * @throws IntrospectionException if an exception occurs during + * introspection. */ public synchronized void setIndexedWriteMethod(Method writeMethod) throws IntrospectionException { diff --git a/src/share/classes/java/beans/Introspector.java b/src/share/classes/java/beans/Introspector.java index 783fcbef3..acc0f77f3 100644 --- a/src/share/classes/java/beans/Introspector.java +++ b/src/share/classes/java/beans/Introspector.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -93,8 +93,17 @@ import sun.reflect.misc.ReflectUtil; public class Introspector { // Flags that can be used to control getBeanInfo: + /** + * Flag to indicate to use of all beaninfo. + */ public final static int USE_ALL_BEANINFO = 1; + /** + * Flag to indicate to ignore immediate beaninfo. + */ public final static int IGNORE_IMMEDIATE_BEANINFO = 2; + /** + * Flag to indicate to ignore all beaninfo. + */ public final static int IGNORE_ALL_BEANINFO = 3; // Static Caches to speed up introspection. @@ -202,7 +211,7 @@ public class Introspector { * If the BeanInfo class for a Java Bean has been previously Introspected * based on the same arguments, then the BeanInfo class is retrieved * from the BeanInfo cache. - * + * @return the BeanInfo for the bean * @param beanClass The bean class to be analyzed. * @param stopClass The baseclass at which to stop the analysis. Any * methods/properties/events in the stopClass or in its baseclasses diff --git a/src/share/classes/java/beans/PersistenceDelegate.java b/src/share/classes/java/beans/PersistenceDelegate.java index 01c5bb123..bbdcdbf06 100644 --- a/src/share/classes/java/beans/PersistenceDelegate.java +++ b/src/share/classes/java/beans/PersistenceDelegate.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -197,6 +197,7 @@ public abstract class PersistenceDelegate { * The default implementation, calls the initialize * method of the type's superclass. * + * @param type the type of the instances * @param oldInstance The instance to be copied. * @param newInstance The instance that is to be modified. * @param out The stream to which any initialization statements should be written. diff --git a/src/share/classes/java/beans/PropertyChangeSupport.java b/src/share/classes/java/beans/PropertyChangeSupport.java index c3c73179b..d55ae76ef 100644 --- a/src/share/classes/java/beans/PropertyChangeSupport.java +++ b/src/share/classes/java/beans/PropertyChangeSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -156,7 +156,7 @@ public class PropertyChangeSupport implements Serializable { * PropertyChangeListenerProxy, perform the cast, and examine * the parameter. * - * 

+     * 
{@code
      * PropertyChangeListener[] listeners = bean.getPropertyChangeListeners();
      * for (int i = 0; i < listeners.length; i++) {
      *   if (listeners[i] instanceof PropertyChangeListenerProxy) {
@@ -168,7 +168,7 @@ public class PropertyChangeSupport implements Serializable {
      *     }
      *   }
      * }
-     *

+     * }
* * @see PropertyChangeListenerProxy * @return all of the PropertyChangeListeners added or an diff --git a/src/share/classes/java/beans/PropertyDescriptor.java b/src/share/classes/java/beans/PropertyDescriptor.java index 0abdcad97..c519b504d 100644 --- a/src/share/classes/java/beans/PropertyDescriptor.java +++ b/src/share/classes/java/beans/PropertyDescriptor.java @@ -243,6 +243,7 @@ public class PropertyDescriptor extends FeatureDescriptor { * Sets the method that should be used to read the property value. * * @param readMethod The new read method. + * @throws IntrospectionException if the read method is invalid */ public synchronized void setReadMethod(Method readMethod) throws IntrospectionException { @@ -313,6 +314,7 @@ public class PropertyDescriptor extends FeatureDescriptor { * Sets the method that should be used to write the property value. * * @param writeMethod The new write method. + * @throws IntrospectionException if the write method is invalid */ public synchronized void setWriteMethod(Method writeMethod) throws IntrospectionException { diff --git a/src/share/classes/java/beans/Transient.java b/src/share/classes/java/beans/Transient.java index 0a2761ce8..165621b39 100644 --- a/src/share/classes/java/beans/Transient.java +++ b/src/share/classes/java/beans/Transient.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -40,7 +40,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * A {@code true} value for the "transient" attribute * indicates to encoders derived from {@link Encoder} * that this feature should be ignored. - *

+ *

* The {@code Transient} annotation may be be used * in any of the methods that are involved * in a {@link FeatureDescriptor} subclass @@ -49,7 +49,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * to put the annotation and it is this declaration * that takes precedence in the case of multiple annotations * being defined for the same feature. - *

+ *

* To declare a feature non-transient in a class * whose superclass declares it transient, * use {@code @Transient(false)}. @@ -64,5 +64,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; @Target({METHOD}) @Retention(RUNTIME) public @interface Transient { + /** + * Returns whether or not the {@code Introspector} should + * construct artifacts for the annotated method. + * @return whether or not the {@code Introspector} should + * construct artifacts for the annotated method + */ boolean value() default true; } diff --git a/src/share/classes/java/beans/VetoableChangeSupport.java b/src/share/classes/java/beans/VetoableChangeSupport.java index 6b7e268eb..293ae5af2 100644 --- a/src/share/classes/java/beans/VetoableChangeSupport.java +++ b/src/share/classes/java/beans/VetoableChangeSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -42,7 +42,7 @@ import java.util.Map.Entry; *

* Here is an example of {@code VetoableChangeSupport} usage that follows * the rules and recommendations laid out in the JavaBeans™ specification: - * 

+ * 
{@code
  * public class MyBean {
  *     private final VetoableChangeSupport vcs = new VetoableChangeSupport(this);
  *
@@ -68,7 +68,7 @@ import java.util.Map.Entry;
  *
  *     [...]
  * }
- * 

+ * }
*

* A {@code VetoableChangeSupport} instance is thread-safe. *

@@ -156,7 +156,7 @@ public class VetoableChangeSupport implements Serializable { * VetoableChangeListenerProxy, perform the cast, and examine * the parameter. * - * 

+     * 
{@code
      * VetoableChangeListener[] listeners = bean.getVetoableChangeListeners();
      * for (int i = 0; i < listeners.length; i++) {
      *        if (listeners[i] instanceof VetoableChangeListenerProxy) {
@@ -168,7 +168,7 @@ public class VetoableChangeSupport implements Serializable {
      *     }
      *   }
      * }
-     *

+     * }
* * @see VetoableChangeListenerProxy * @return all of the VetoableChangeListeners added or an diff --git a/src/share/classes/java/beans/beancontext/BeanContext.java b/src/share/classes/java/beans/beancontext/BeanContext.java index c6217289f..308147b9e 100644 --- a/src/share/classes/java/beans/beancontext/BeanContext.java +++ b/src/share/classes/java/beans/beancontext/BeanContext.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -64,10 +64,12 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V * and is defined by the * java.beans.Beans.instantiate() method. * + * @return a javaBean named as a child of this + * BeanContext * @param beanName The name of the JavaBean to instantiate * as a child of this BeanContext - * @throws IOException - * @throws ClassNotFoundException if the class identified + * @throws IOException if an IO problem occurs + * @throws ClassNotFoundException if the class identified * by the beanName parameter is not found */ Object instantiateChild(String beanName) throws IOException, ClassNotFoundException; @@ -83,7 +85,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V * @return an InputStream for reading the resource, * or null if the resource could not * be found. - * @throws IllegalArgumentException if + * @throws IllegalArgumentException if * the resource is not valid */ InputStream getResourceAsStream(String name, BeanContextChild bcc) throws IllegalArgumentException; @@ -98,7 +100,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V * @param bcc the specified child * @return a URL for the named * resource for the specified child - * @throws IllegalArgumentException + * @throws IllegalArgumentException * if the resource is not valid */ URL getResource(String name, BeanContextChild bcc) throws IllegalArgumentException; @@ -109,7 +111,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V * this BeanContext whenever it adds * or removes a child Component(s). * - * @param bcml the BeanContextMembershipListener to be added + * @param bcml the BeanContextMembershipListener to be added */ void addBeanContextMembershipListener(BeanContextMembershipListener bcml); diff --git a/src/share/classes/java/beans/beancontext/BeanContextChild.java b/src/share/classes/java/beans/beancontext/BeanContextChild.java index 841e3ccbc..e84b7a7ee 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextChild.java +++ b/src/share/classes/java/beans/beancontext/BeanContextChild.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -82,7 +82,7 @@ public interface BeanContextChild { *

* @param bc The BeanContext with which * to associate this BeanContextChild. - * @throws PropertyVetoException if the + * @throws PropertyVetoException if the * addition of the specified BeanContext is refused. */ void setBeanContext(BeanContext bc) throws PropertyVetoException; diff --git a/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java b/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java index 056913b65..b2b855867 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java +++ b/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java @@ -78,6 +78,7 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer * construct a BeanContextChildSupport where the JavaBean component * itself implements BeanContextChild, and encapsulates this, delegating * that interface to this implementation + * @param bcc the underlying bean context child */ public BeanContextChildSupport(BeanContextChild bcc) { @@ -94,7 +95,7 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer * this BeanContextChildSupport. * @param bc the new value to be assigned to the BeanContext * property - * @throws PropertyVetoException if the change is rejected + * @throws PropertyVetoException if the change is rejected */ public synchronized void setBeanContext(BeanContext bc) throws PropertyVetoException { if (bc == beanContext) return; @@ -361,6 +362,9 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer */ protected VetoableChangeSupport vcSupport; + /** + * The bean context. + */ protected transient BeanContext beanContext; /** diff --git a/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java b/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java index 6b5f4f560..24406d4e7 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java +++ b/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -103,6 +103,7 @@ public class BeanContextMembershipEvent extends BeanContextEvent { * Is the child specified affected by the event? * @return true if affected, false * if not + * @param child the object to check for being affected */ public boolean contains(Object child) { return children.contains(child); diff --git a/src/share/classes/java/beans/beancontext/BeanContextServices.java b/src/share/classes/java/beans/beancontext/BeanContextServices.java index 168056c26..0348817bf 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextServices.java +++ b/src/share/classes/java/beans/beancontext/BeanContextServices.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -60,6 +60,7 @@ public interface BeanContextServices extends BeanContext, BeanContextServicesLis * @param serviceClass the service to add * @param serviceProvider the BeanContextServiceProvider * associated with the service + * @return true if the service was successful added, false otherwise */ boolean addService(Class serviceClass, BeanContextServiceProvider serviceProvider); @@ -108,7 +109,7 @@ public interface BeanContextServices extends BeanContext, BeanContextServicesLis * @param bcsrl the * BeanContextServiceRevokedListener to notify * if the service should later become revoked - * @throws TooManyListenersException + * @throws TooManyListenersException if there are too many listeners * @return a reference to this context's named * Service as requested or null */ diff --git a/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java b/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java index 94d104b14..ca0942efe 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java +++ b/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2009, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -603,12 +603,16 @@ public class BeanContextServicesSupport extends BeanContextSupport serviceProvider = bcsp; } + /** + * Returns the service provider. + * @return the service provider + */ protected BeanContextServiceProvider getServiceProvider() { return serviceProvider; } - /* - * fields + /** + * The service provider. */ protected BeanContextServiceProvider serviceProvider; @@ -618,6 +622,9 @@ public class BeanContextServicesSupport extends BeanContextSupport * subclasses can override this method to create new subclasses of * BCSSServiceProvider without having to overrride addService() in * order to instantiate. + * @param sc the class + * @param bcsp the service provider + * @return a service provider without overriding addService() */ protected BCSSServiceProvider createBCSSServiceProvider(Class sc, BeanContextServiceProvider bcsp) { @@ -629,7 +636,7 @@ public class BeanContextServicesSupport extends BeanContextSupport /** * add a BeanContextServicesListener * - * @throws NullPointerException + * @throws NullPointerException if the argument is null */ public void addBeanContextServicesListener(BeanContextServicesListener bcsl) { @@ -660,6 +667,8 @@ public class BeanContextServicesSupport extends BeanContextSupport /** * add a service + * @param serviceClass the service class + * @param bcsp the service provider */ public boolean addService(Class serviceClass, BeanContextServiceProvider bcsp) { @@ -668,6 +677,10 @@ public class BeanContextServicesSupport extends BeanContextSupport /** * add a service + * @param serviceClass the service class + * @param bcsp the service provider + * @param fireEvent whether or not an event should be fired + * @return true if the service was successfully added */ protected boolean addService(Class serviceClass, BeanContextServiceProvider bcsp, boolean fireEvent) { @@ -709,6 +722,9 @@ public class BeanContextServicesSupport extends BeanContextSupport /** * remove a service + * @param serviceClass the service class + * @param bcsp the service provider + * @param revokeCurrentServicesNow whether or not to revoke the service */ public void revokeService(Class serviceClass, BeanContextServiceProvider bcsp, boolean revokeCurrentServicesNow) { @@ -1067,6 +1083,7 @@ public class BeanContextServicesSupport extends BeanContextSupport /** * Fires a BeanContextServiceEvent notifying of a new service. + * @param serviceClass the service class */ protected final void fireServiceAdded(Class serviceClass) { BeanContextServiceAvailableEvent bcssae = new BeanContextServiceAvailableEvent(getBeanContextServicesPeer(), serviceClass); @@ -1109,6 +1126,8 @@ public class BeanContextServicesSupport extends BeanContextSupport * Fires a BeanContextServiceRevokedEvent * indicating that a particular service is * no longer available. + * @param serviceClass the service class + * @param revokeNow whether or not the event should be revoked now */ protected final void fireServiceRevoked(Class serviceClass, boolean revokeNow) { Object[] copy; diff --git a/src/share/classes/java/beans/beancontext/BeanContextSupport.java b/src/share/classes/java/beans/beancontext/BeanContextSupport.java index 85b1a5a29..a549e2dc3 100644 --- a/src/share/classes/java/beans/beancontext/BeanContextSupport.java +++ b/src/share/classes/java/beans/beancontext/BeanContextSupport.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -62,7 +62,6 @@ import java.util.Map; /** * This helper class provides a utility implementation of the * java.beans.beancontext.BeanContext interface. - *

*

* Since this class directly implements the BeanContext interface, the class * can, and is intended to be used either by subclassing this implementation, @@ -351,9 +350,8 @@ public class BeanContextSupport extends BeanContextChildSupport * of Child without having to override add() or the other Collection * methods that add children to the set. *

- * * @param targetChild the child to create the Child on behalf of - * @param peer the peer if the tragetChild and the peer are related by an implementation of BeanContextProxy + * @param peer the peer if the tragetChild and the peer are related by an implementation of BeanContextProxy * @return Subtype-specific subclass of Child without overriding collection methods */ protected BCSChild createBCSChild(Object targetChild, Object peer) { @@ -492,6 +490,7 @@ public class BeanContextSupport extends BeanContextChildSupport * @param callChildSetBC used to indicate that * the child should be notified that it is no * longer nested in this BeanContext. + * @return whether or not was present before being removed */ protected boolean remove(Object targetChild, boolean callChildSetBC) { @@ -580,7 +579,8 @@ public class BeanContextSupport extends BeanContextChildSupport /** * add Collection to set of Children (Unsupported) * implementations must synchronized on the hierarchy lock and "children" protected field - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException thrown unconditionally by this implementation + * @return this implementation unconditionally throws {@code UnsupportedOperationException} */ public boolean addAll(Collection c) { throw new UnsupportedOperationException(); @@ -589,7 +589,9 @@ public class BeanContextSupport extends BeanContextChildSupport /** * remove all specified children (Unsupported) * implementations must synchronized on the hierarchy lock and "children" protected field - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException thrown unconditionally by this implementation + * @return this implementation unconditionally throws {@code UnsupportedOperationException} + */ public boolean removeAll(Collection c) { throw new UnsupportedOperationException(); @@ -599,7 +601,8 @@ public class BeanContextSupport extends BeanContextChildSupport /** * retain only specified children (Unsupported) * implementations must synchronized on the hierarchy lock and "children" protected field - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException thrown unconditionally by this implementation + * @return this implementation unconditionally throws {@code UnsupportedOperationException} */ public boolean retainAll(Collection c) { throw new UnsupportedOperationException(); @@ -608,7 +611,7 @@ public class BeanContextSupport extends BeanContextChildSupport /** * clear the children (Unsupported) * implementations must synchronized on the hierarchy lock and "children" protected field - * @throws UnsupportedOperationException + * @throws UnsupportedOperationException thrown unconditionally by this implementation */ public void clear() { throw new UnsupportedOperationException(); @@ -618,7 +621,7 @@ public class BeanContextSupport extends BeanContextChildSupport * Adds a BeanContextMembershipListener * * @param bcml the BeanContextMembershipListener to add - * @throws NullPointerException + * @throws NullPointerException if the argument is null */ public void addBeanContextMembershipListener(BeanContextMembershipListener bcml) { @@ -636,7 +639,7 @@ public class BeanContextSupport extends BeanContextChildSupport * Removes a BeanContextMembershipListener * * @param bcml the BeanContextMembershipListener to remove - * @throws NullPointerException + * @throws NullPointerException if the argument is null */ public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml) { @@ -655,7 +658,7 @@ public class BeanContextSupport extends BeanContextChildSupport * @param bcc the child object making the request. * * @return the requested resource as an InputStream - * @throws NullPointerException + * @throws NullPointerException if the argument is null */ public InputStream getResourceAsStream(String name, BeanContextChild bcc) { @@ -849,6 +852,8 @@ public class BeanContextSupport extends BeanContextChildSupport * * This method should not however be used by subclasses to replace their * own implementation (if any) of writeObject(). + * @param oos the {@code ObjectOutputStream} to use during serialization + * @throws IOException if serialization failed */ protected void bcsPreSerializationHook(ObjectOutputStream oos) throws IOException { @@ -864,6 +869,9 @@ public class BeanContextSupport extends BeanContextChildSupport * * This method should not however be used by subclasses to replace their * own implementation (if any) of readObject(). + * @param ois the {@code ObjectInputStream} to use during deserialization + * @throws IOException if deserialization failed + * @throws ClassNotFoundException if needed classes are not found */ protected void bcsPreDeserializationHook(ObjectInputStream ois) throws IOException, ClassNotFoundException { @@ -914,6 +922,8 @@ public class BeanContextSupport extends BeanContextChildSupport * used by readObject to deserialize a collection. * @param ois the ObjectInputStream to use * @param coll the Collection + * @throws IOException if deserialization failed + * @throws ClassNotFoundException if needed classes are not found */ protected final void deserialize(ObjectInputStream ois, Collection coll) throws IOException, ClassNotFoundException { int count = 0; @@ -1005,6 +1015,9 @@ public class BeanContextSupport extends BeanContextChildSupport * When an instance of this class is used as a delegate for the * implementation of the BeanContext protocols (and its subprotocols) * there exists a 'chicken and egg' problem during deserialization + * @param ois the ObjectInputStream to use + * @throws IOException if deserialization failed + * @throws ClassNotFoundException if needed classes are not found */ public final void readChildren(ObjectInputStream ois) throws IOException, ClassNotFoundException { @@ -1122,6 +1135,7 @@ public class BeanContextSupport extends BeanContextChildSupport * immediately prior to their being added to the BeanContext. *

* + * @param targetChild the child to create the Child on behalf of * @return true iff the child may be added to this BeanContext, otherwise false. */ @@ -1136,6 +1150,7 @@ public class BeanContextSupport extends BeanContextChildSupport * immediately prior to their being removed from the BeanContext. *

* + * @param targetChild the child to create the Child on behalf of * @return true iff the child may be removed from this BeanContext, otherwise false. */ @@ -1147,6 +1162,8 @@ public class BeanContextSupport extends BeanContextChildSupport * subclasses may override this method to simply extend add() semantics * after the child has been added and before the event notification has * occurred. The method is called with the child synchronized. + * @param child the child + * @param bcsc the BCSChild */ protected void childJustAddedHook(Object child, BCSChild bcsc) { @@ -1156,6 +1173,8 @@ public class BeanContextSupport extends BeanContextChildSupport * subclasses may override this method to simply extend remove() semantics * after the child has been removed and before the event notification has * occurred. The method is called with the child synchronized. + * @param child the child + * @param bcsc the BCSChild */ protected void childJustRemovedHook(Object child, BCSChild bcsc) { @@ -1254,6 +1273,7 @@ public class BeanContextSupport extends BeanContextChildSupport /** * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface + * @param bcme the event to fire */ protected final void fireChildrenAdded(BeanContextMembershipEvent bcme) { @@ -1267,6 +1287,7 @@ public class BeanContextSupport extends BeanContextChildSupport /** * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface + * @param bcme the event to fire */ protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme) { -- GitLab