src/share/classes/java/beans/beancontext/BeanContextSupport.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 1997, 2004, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 60,70 ****
/**
* 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,
* or via ad-hoc delegation of an instance of this class from another.
* </p>
--- 60,69 ----
*** 349,359 ****
* <p>
* Subclasses can override this method to insert their own subclass
* 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
*/
protected BCSChild createBCSChild(Object targetChild, Object peer) {
--- 348,358 ----
* <p>
* Subclasses can override this method to insert their own subclass
* of Child without having to override add() or the other Collection
* methods that add children to the set.
* </p>
! * @return Subtype-specific subclass of Child without overriding collection methods
* @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
*/
protected BCSChild createBCSChild(Object targetChild, Object peer) {
*** 490,499 ****
--- 489,499 ----
* by <tt>remove()</tt> invocation.
* @param targetChild the JavaBean, BeanContext, or Object to be removed
* @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) {
if (targetChild == null) throw new IllegalArgumentException();
*** 578,626 ****
}
/**
* add Collection to set of Children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException
*/
public boolean addAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* remove all specified children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException
*/
public boolean removeAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* retain only specified children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException
*/
public boolean retainAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* clear the children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException
*/
public void clear() {
throw new UnsupportedOperationException();
}
/**
* Adds a BeanContextMembershipListener
*
* @param bcml the BeanContextMembershipListener to add
! * @throws NullPointerException
*/
public void addBeanContextMembershipListener(BeanContextMembershipListener bcml) {
if (bcml == null) throw new NullPointerException("listener");
--- 578,630 ----
}
/**
* add Collection to set of Children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException thrown unconditionally by this implementation
! * @return this implementation unconditionally throws {@code UnsupportedOperationException}
*/
public boolean addAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* remove all specified children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException thrown unconditionally by this implementation
! * @return this implementation unconditionally throws {@code UnsupportedOperationException}
!
*/
public boolean removeAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* retain only specified children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException thrown unconditionally by this implementation
! * @return this implementation unconditionally throws {@code UnsupportedOperationException}
*/
public boolean retainAll(Collection c) {
throw new UnsupportedOperationException();
}
/**
* clear the children (Unsupported)
* implementations must synchronized on the hierarchy lock and "children" protected field
! * @throws UnsupportedOperationException thrown unconditionally by this implementation
*/
public void clear() {
throw new UnsupportedOperationException();
}
/**
* Adds a BeanContextMembershipListener
*
* @param bcml the BeanContextMembershipListener to add
! * @throws NullPointerException if the argument is null
*/
public void addBeanContextMembershipListener(BeanContextMembershipListener bcml) {
if (bcml == null) throw new NullPointerException("listener");
*** 634,644 ****
/**
* Removes a BeanContextMembershipListener
*
* @param bcml the BeanContextMembershipListener to remove
! * @throws NullPointerException
*/
public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml) {
if (bcml == null) throw new NullPointerException("listener");
--- 638,648 ----
/**
* Removes a BeanContextMembershipListener
*
* @param bcml the BeanContextMembershipListener to remove
! * @throws NullPointerException if the argument is null
*/
public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml) {
if (bcml == null) throw new NullPointerException("listener");
*** 653,663 ****
/**
* @param name the name of the resource requested.
* @param bcc the child object making the request.
*
* @return the requested resource as an InputStream
! * @throws NullPointerException
*/
public InputStream getResourceAsStream(String name, BeanContextChild bcc) {
if (name == null) throw new NullPointerException("name");
if (bcc == null) throw new NullPointerException("bcc");
--- 657,667 ----
/**
* @param name the name of the resource requested.
* @param bcc the child object making the request.
*
* @return the requested resource as an InputStream
! * @throws NullPointerException if the argument is null
*/
public InputStream getResourceAsStream(String name, BeanContextChild bcc) {
if (name == null) throw new NullPointerException("name");
if (bcc == null) throw new NullPointerException("bcc");
*** 847,856 ****
--- 851,862 ----
* serialization of their state prior to this superclass serializing
* the children.
*
* 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 {
}
*** 862,871 ****
--- 868,880 ----
* deserialization of their state prior to this superclass deserializing
* the children.
*
* 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 {
}
*** 912,921 ****
--- 921,932 ----
/**
* 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;
count = ois.readInt();
*** 1003,1012 ****
--- 1014,1026 ----
/**
* 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 {
int count = serializable;
*** 1120,1129 ****
--- 1134,1144 ----
* Subclasses of this class may override, or envelope, this method to
* add validation behavior for the BeanContext to examine child objects
* 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.
*/
protected boolean validatePendingAdd(Object targetChild) {
return true;
*** 1134,1143 ****
--- 1149,1159 ----
* Subclasses of this class may override, or envelope, this method to
* add validation behavior for the BeanContext to examine child objects
* 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.
*/
protected boolean validatePendingRemove(Object targetChild) {
return true;
*** 1145,1163 ****
--- 1161,1183 ----
/**
* 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) {
}
/**
* 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) {
}
*** 1252,1261 ****
--- 1272,1282 ----
}
}
/**
* Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
+ * @param bcme the event to fire
*/
protected final void fireChildrenAdded(BeanContextMembershipEvent bcme) {
Object[] copy;
*** 1265,1274 ****
--- 1286,1296 ----
((BeanContextMembershipListener)copy[i]).childrenAdded(bcme);
}
/**
* Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
+ * @param bcme the event to fire
*/
protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme) {
Object[] copy;