1. /*
  2. * @(#)BeanContext.java 1.22 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.beans.beancontext;
  8. import java.beans.DesignMode;
  9. import java.beans.Visibility;
  10. import java.io.InputStream;
  11. import java.io.IOException;
  12. import java.net.URL;
  13. import java.util.Collection;
  14. import java.util.Locale;
  15. /**
  16. * <p>
  17. * The BeanContext acts a logical hierarchical container for JavaBeans.
  18. * </p>
  19. *
  20. * @author Laurence P. G. Cable
  21. * @version 1.22, 01/23/03
  22. * @since 1.2
  23. *
  24. * @see java.beans.Beans
  25. * @see java.beans.beancontext.BeanContextChild
  26. * @see java.beans.beancontext.BeanContextMembershipListener
  27. * @see java.beans.PropertyChangeEvent
  28. * @see java.beans.VetoableChangeEvent
  29. * @see java.beans.DesignMode
  30. * @see java.beans.Visibility
  31. * @see java.util.Collection
  32. */
  33. public interface BeanContext extends BeanContextChild, Collection, DesignMode, Visibility {
  34. /**
  35. * Instantiate the javaBean named as a
  36. * child of this <code>BeanContext</code>.
  37. * The implementation of the JavaBean is
  38. * derived from the value of the beanName parameter,
  39. * and is defined by the
  40. * <code>java.beans.Beans.instantiate()</code> method.
  41. *
  42. * @param beanName The name of the JavaBean to instantiate
  43. * as a child of this <code>BeanContext</code>
  44. * @throws <code>IOException</code>
  45. * @throws <code>ClassNotFoundException</code> if the class identified
  46. * by the beanName parameter is not found
  47. */
  48. Object instantiateChild(String beanName) throws IOException, ClassNotFoundException;
  49. /**
  50. * Analagous to <code>java.lang.ClassLoader.getResourceAsStream()</code>,
  51. * this method allows a <code>BeanContext</code> implementation
  52. * to interpose behavior between the child <code>Component</code>
  53. * and underlying <code>ClassLoader</code>.
  54. *
  55. * @param name the resource name
  56. * @param bcc the specified child
  57. * @return an <code>InputStream</code> for reading the resource,
  58. * or <code>null</code> if the resource could not
  59. * be found.
  60. * @throws <code>IllegalArgumentException</code> if
  61. * the resource is not valid
  62. */
  63. InputStream getResourceAsStream(String name, BeanContextChild bcc) throws IllegalArgumentException;
  64. /**
  65. * Analagous to <code>java.lang.ClassLoader.getResource()</code>, this
  66. * method allows a <code>BeanContext</code> implementation to interpose
  67. * behavior between the child <code>Component</code>
  68. * and underlying <code>ClassLoader</code>.
  69. *
  70. * @param name the resource name
  71. * @param bcc the specified child
  72. * @return a <code>URL</code> for the named
  73. * resource for the specified child
  74. * @throws <code>IllegalArgumentException</code>
  75. * if the resource is not valid
  76. */
  77. URL getResource(String name, BeanContextChild bcc) throws IllegalArgumentException;
  78. /**
  79. * Adds the specified <code>BeanContextMembershipListener</code>
  80. * to receive <code>BeanContextMembershipEvents</code> from
  81. * this <code>BeanContext</code> whenever it adds
  82. * or removes a child <code>Component</code>(s).
  83. *
  84. * @param bcml the <code>BeanContextMembershipListener</code> to be added
  85. */
  86. void addBeanContextMembershipListener(BeanContextMembershipListener bcml);
  87. /**
  88. * Removes the specified <code>BeanContextMembershipListener</code>
  89. * so that it no longer receives <code>BeanContextMembershipEvent</code>s
  90. * when the child <code>Component</code>(s) are added or removed.
  91. *
  92. * @param bcml the <code>BeanContextMembershipListener</code>
  93. * to be removed
  94. */
  95. void removeBeanContextMembershipListener(BeanContextMembershipListener bcml);
  96. /**
  97. * This global lock is used by both <code>BeanContext</code>
  98. * and <code>BeanContextServices</code> implementors
  99. * to serialize changes in a <code>BeanContext</code>
  100. * hierarchy and any service requests etc.
  101. */
  102. public static final Object globalHierarchyLock = new Object();
  103. }