Mercurial > hg > openjdk > lambda > jdk
changeset 9520:d5694d78ebc6
8022406: Fix doclint issues in java.beans
Reviewed-by: prr
line wrap: on
line diff
--- a/src/share/classes/java/beans/AppletInitializer.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/AppletInitializer.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * the Applet with its Container during the subsequent invocation of its * addChildren() method. * </ol> - * </p> * * @param newAppletBean The newly instantiated JavaBean * @param bCtxt The BeanContext intended for this Applet, or
--- a/src/share/classes/java/beans/Beans.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/Beans.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * <p> * Instantiate a JavaBean. * </p> - * + * @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 @@ * <p> * Instantiate a JavaBean. * </p> + * @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 @@ * 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 @@ * 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 @@ return Introspector.isSubclass(bean.getClass(), targetType); } - /** * Test if we are in design-mode. *
--- a/src/share/classes/java/beans/ConstructorProperties.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/ConstructorProperties.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ 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.</p> + and {@code getY()} or the other way around. @since 1.6 */
--- a/src/share/classes/java/beans/DefaultPersistenceDelegate.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/DefaultPersistenceDelegate.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * 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.
--- a/src/share/classes/java/beans/EventHandler.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/EventHandler.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ *</pre> *</blockquote> * + * @param <T> 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 @@ *</pre> *</blockquote> * + * @param <T> 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 @@ * </pre> *</blockquote> * + * @param <T> 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
--- a/src/share/classes/java/beans/Expression.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/Expression.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * replaces this default value in the same way that any other value * would, ensuring that expressions are never evaluated more than once. * <p> - * See the <code>excecute</code> method for details on how + * See the <code>execute</code> method for details on how * methods are chosen using the dynamic types of the target * and arguments. * @@ -147,6 +147,8 @@ * @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) {
--- a/src/share/classes/java/beans/IndexedPropertyDescriptor.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/IndexedPropertyDescriptor.java Tue Aug 06 16:01:39 2013 -0700 @@ -207,6 +207,8 @@ * 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 @@ * 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 {
--- a/src/share/classes/java/beans/Introspector.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/Introspector.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ 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 @@ * 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
--- a/src/share/classes/java/beans/PersistenceDelegate.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/PersistenceDelegate.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * The default implementation, calls the <code>initialize</code> * 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.
--- a/src/share/classes/java/beans/PropertyChangeSupport.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/PropertyChangeSupport.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * <code>PropertyChangeListenerProxy</code>, perform the cast, and examine * the parameter. * - * <pre> + * <pre>{@code * PropertyChangeListener[] listeners = bean.getPropertyChangeListeners(); * for (int i = 0; i < listeners.length; i++) { * if (listeners[i] instanceof PropertyChangeListenerProxy) { @@ -168,7 +168,7 @@ * } * } * } - *</pre> + * }</pre> * * @see PropertyChangeListenerProxy * @return all of the <code>PropertyChangeListeners</code> added or an
--- a/src/share/classes/java/beans/PropertyDescriptor.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/PropertyDescriptor.java Tue Aug 06 16:01:39 2013 -0700 @@ -243,6 +243,7 @@ * 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 @@ * 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 {
--- a/src/share/classes/java/beans/Transient.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/Transient.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * A {@code true} value for the "transient" attribute * indicates to encoders derived from {@link Encoder} * that this feature should be ignored. - * <p/> + * <p> * 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 @@ * to put the annotation and it is this declaration * that takes precedence in the case of multiple annotations * being defined for the same feature. - * <p/> + * <p> * To declare a feature non-transient in a class * whose superclass declares it transient, * use {@code @Transient(false)}. @@ -64,5 +64,11 @@ @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; }
--- a/src/share/classes/java/beans/VetoableChangeSupport.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/VetoableChangeSupport.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * <p> * Here is an example of {@code VetoableChangeSupport} usage that follows * the rules and recommendations laid out in the JavaBeans™ specification: - * <pre> + * <pre>{@code * public class MyBean { * private final VetoableChangeSupport vcs = new VetoableChangeSupport(this); * @@ -68,7 +68,7 @@ * * [...] * } - * </pre> + * }</pre> * <p> * A {@code VetoableChangeSupport} instance is thread-safe. * <p> @@ -156,7 +156,7 @@ * <code>VetoableChangeListenerProxy</code>, perform the cast, and examine * the parameter. * - * <pre> + * <pre>{@code * VetoableChangeListener[] listeners = bean.getVetoableChangeListeners(); * for (int i = 0; i < listeners.length; i++) { * if (listeners[i] instanceof VetoableChangeListenerProxy) { @@ -168,7 +168,7 @@ * } * } * } - *</pre> + * }</pre> * * @see VetoableChangeListenerProxy * @return all of the <code>VetoableChangeListeners</code> added or an
--- a/src/share/classes/java/beans/beancontext/BeanContext.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContext.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * and is defined by the * <code>java.beans.Beans.instantiate()</code> method. * + * @return a javaBean named as a child of this + * <code>BeanContext</code> * @param beanName The name of the JavaBean to instantiate * as a child of this <code>BeanContext</code> - * @throws <code>IOException</code> - * @throws <code>ClassNotFoundException</code> 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 @@ * @return an <code>InputStream</code> for reading the resource, * or <code>null</code> if the resource could not * be found. - * @throws <code>IllegalArgumentException</code> if + * @throws IllegalArgumentException if * the resource is not valid */ InputStream getResourceAsStream(String name, BeanContextChild bcc) throws IllegalArgumentException; @@ -98,7 +100,7 @@ * @param bcc the specified child * @return a <code>URL</code> for the named * resource for the specified child - * @throws <code>IllegalArgumentException</code> + * @throws IllegalArgumentException * if the resource is not valid */ URL getResource(String name, BeanContextChild bcc) throws IllegalArgumentException; @@ -109,7 +111,7 @@ * this <code>BeanContext</code> whenever it adds * or removes a child <code>Component</code>(s). * - * @param bcml the <code>BeanContextMembershipListener</code> to be added + * @param bcml the BeanContextMembershipListener to be added */ void addBeanContextMembershipListener(BeanContextMembershipListener bcml);
--- a/src/share/classes/java/beans/beancontext/BeanContextChild.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextChild.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * </p> * @param bc The <code>BeanContext</code> with which * to associate this <code>BeanContextChild</code>. - * @throws <code>PropertyVetoException</code> if the + * @throws PropertyVetoException if the * addition of the specified <code>BeanContext</code> is refused. */ void setBeanContext(BeanContext bc) throws PropertyVetoException;
--- a/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextChildSupport.java Tue Aug 06 16:01:39 2013 -0700 @@ -78,6 +78,7 @@ * 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 @@ * this <code>BeanContextChildSupport</code>. * @param bc the new value to be assigned to the <code>BeanContext</code> * property - * @throws <code>PropertyVetoException</code> 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 @@ */ protected VetoableChangeSupport vcSupport; + /** + * The bean context. + */ protected transient BeanContext beanContext; /**
--- a/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * Is the child specified affected by the event? * @return <code>true</code> if affected, <code>false</code> * if not + * @param child the object to check for being affected */ public boolean contains(Object child) { return children.contains(child);
--- a/src/share/classes/java/beans/beancontext/BeanContextServices.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextServices.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ * @param serviceClass the service to add * @param serviceProvider the <code>BeanContextServiceProvider</code> * associated with the service + * @return true if the service was successful added, false otherwise */ boolean addService(Class serviceClass, BeanContextServiceProvider serviceProvider); @@ -108,7 +109,7 @@ * @param bcsrl the * <code>BeanContextServiceRevokedListener</code> 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 <code>null</code> */
--- a/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ 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 @@ * 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 @@ /** * add a BeanContextServicesListener * - * @throws NullPointerException + * @throws NullPointerException if the argument is null */ public void addBeanContextServicesListener(BeanContextServicesListener bcsl) { @@ -660,6 +667,8 @@ /** * add a service + * @param serviceClass the service class + * @param bcsp the service provider */ public boolean addService(Class serviceClass, BeanContextServiceProvider bcsp) { @@ -668,6 +677,10 @@ /** * 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 @@ /** * 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 @@ /** * Fires a <tt>BeanContextServiceEvent</tt> 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 @@ * Fires a <tt>BeanContextServiceRevokedEvent</tt> * 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;
--- a/src/share/classes/java/beans/beancontext/BeanContextSupport.java Tue Aug 06 14:33:56 2013 -0700 +++ b/src/share/classes/java/beans/beancontext/BeanContextSupport.java Tue Aug 06 16:01:39 2013 -0700 @@ -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 @@ /** * This helper class provides a utility implementation of the * java.beans.beancontext.BeanContext interface. - * </p> * <p> * 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 @@ * of Child without having to override add() or the other Collection * methods that add children to the set. * </p> - * * @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 @@ * @param callChildSetBC used to indicate that * the child should be notified that it is no * longer nested in this <tt>BeanContext</tt>. + * @return whether or not was present before being removed */ protected boolean remove(Object targetChild, boolean callChildSetBC) { @@ -580,7 +579,8 @@ /** * 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 @@ /** * 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 @@ /** * 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 @@ /** * 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 @@ * 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 @@ * 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 @@ * @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 @@ * * 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 @@ * * 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 @@ * 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 @@ * 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 @@ * immediately prior to their being added to the BeanContext. * </p> * + * @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 @@ * immediately prior to their being removed from the BeanContext. * </p> * + * @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 @@ * 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 @@ * 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 @@ /** * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface + * @param bcme the event to fire */ protected final void fireChildrenAdded(BeanContextMembershipEvent bcme) { @@ -1267,6 +1287,7 @@ /** * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface + * @param bcme the event to fire */ protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme) {