1 /* 2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.beans.beancontext; 27 28 import java.beans.DesignMode; 29 import java.beans.Visibility; 30 31 import java.io.InputStream; 32 import java.io.IOException; 33 34 import java.net.URL; 35 36 import java.util.Collection; 37 import java.util.Locale; 38 39 /** 40 * <p> 41 * The BeanContext acts a logical hierarchical container for JavaBeans. 42 * </p> 43 * 44 * @author Laurence P. G. Cable 45 * @since 1.2 46 * 47 * @see java.beans.Beans 48 * @see java.beans.beancontext.BeanContextChild 49 * @see java.beans.beancontext.BeanContextMembershipListener 50 * @see java.beans.PropertyChangeEvent 51 * @see java.beans.DesignMode 52 * @see java.beans.Visibility 53 * @see java.util.Collection 54 */ 55 56 @SuppressWarnings("rawtypes") 57 public interface BeanContext extends BeanContextChild, Collection, DesignMode, Visibility { 58 59 /** 60 * Instantiate the javaBean named as a 61 * child of this <code>BeanContext</code>. 62 * The implementation of the JavaBean is 63 * derived from the value of the beanName parameter, 64 * and is defined by the 65 * <code>java.beans.Beans.instantiate()</code> method. 66 * 67 * @return a javaBean named as a child of this 68 * <code>BeanContext</code> 69 * @param beanName The name of the JavaBean to instantiate 70 * as a child of this <code>BeanContext</code> 71 * @throws IOException if an IO problem occurs 72 * @throws ClassNotFoundException if the class identified 73 * by the beanName parameter is not found 74 */ 75 Object instantiateChild(String beanName) throws IOException, ClassNotFoundException; 76 77 /** 78 * Analagous to <code>java.lang.ClassLoader.getResourceAsStream()</code>, 79 * this method allows a <code>BeanContext</code> implementation 80 * to interpose behavior between the child <code>Component</code> 81 * and underlying <code>ClassLoader</code>. 82 * 83 * @param name the resource name 84 * @param bcc the specified child 85 * @return an <code>InputStream</code> for reading the resource, 86 * or <code>null</code> if the resource could not 87 * be found. 88 * @throws IllegalArgumentException if 89 * the resource is not valid 90 */ 91 InputStream getResourceAsStream(String name, BeanContextChild bcc) throws IllegalArgumentException; 92 93 /** 94 * Analagous to <code>java.lang.ClassLoader.getResource()</code>, this 95 * method allows a <code>BeanContext</code> implementation to interpose 96 * behavior between the child <code>Component</code> 97 * and underlying <code>ClassLoader</code>. 98 * 99 * @param name the resource name 100 * @param bcc the specified child 101 * @return a <code>URL</code> for the named 102 * resource for the specified child 103 * @throws IllegalArgumentException 104 * if the resource is not valid 105 */ 106 URL getResource(String name, BeanContextChild bcc) throws IllegalArgumentException; 107 108 /** 109 * Adds the specified <code>BeanContextMembershipListener</code> 110 * to receive <code>BeanContextMembershipEvents</code> from 111 * this <code>BeanContext</code> whenever it adds 112 * or removes a child <code>Component</code>(s). 113 * 114 * @param bcml the BeanContextMembershipListener to be added 115 */ 116 void addBeanContextMembershipListener(BeanContextMembershipListener bcml); 117 118 /** 119 * Removes the specified <code>BeanContextMembershipListener</code> 120 * so that it no longer receives <code>BeanContextMembershipEvent</code>s 121 * when the child <code>Component</code>(s) are added or removed. 122 * 123 * @param bcml the <code>BeanContextMembershipListener</code> 124 * to be removed 125 */ 126 void removeBeanContextMembershipListener(BeanContextMembershipListener bcml); 127 128 /** 129 * This global lock is used by both <code>BeanContext</code> 130 * and <code>BeanContextServices</code> implementors 131 * to serialize changes in a <code>BeanContext</code> 132 * hierarchy and any service requests etc. 133 */ 134 public static final Object globalHierarchyLock = new Object(); 135 }