001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.event;
019:
020: import javax.naming.Context;
021: import javax.naming.Name;
022: import javax.naming.NamingException;
023:
024: /**
025: * This interface is for registering and deregistering to receive events about
026: * objects that are bound in a context.
027: * <p>
028: * Listeners register an interest in a target object or objects. The context
029: * might not yet have a binding for the target, and it is optional whether a
030: * context will support registering for events about an object that is not
031: * bound. If the context does not support it then
032: * <code>addNamingListener()</code> should throw a
033: * <code>NameNotFoundException</code>. Alternatively, if this is not
034: * possible, the <code>EventContext</code> should send the listener a
035: * <code>NamingExceptionEvent</code> with the information. A
036: * <code>NamingExceptionEvent</code> is also used to notify listeners who have
037: * registered interest in a target that is subsequently deleted, if the context
038: * only allows registration for currently bound objects.
039: * </p>
040: * <p>
041: * Listeners can register for events affecting the context itself, which as
042: * usual is referred to by the empty name.
043: * </p>
044: * <p>
045: * When a listener receives a <code>NamingExceptionEvent</code> it is
046: * deregistered.
047: * </p>
048: * <p>
049: * When <code>Context</code>.closed is called on an <code>EventContext</code>,
050: * all of its listeners are deregistered.
051: * </p>
052: * <p>
053: * Listener implementations may choose to implement more than one sub-interface
054: * of <code>NamingListener</code>, in order to be notified of more than one
055: * type of event.
056: * </p>
057: * <p>
058: * Event context implementations are not expected to be thread safe.
059: * </p>
060: */
061: public interface EventContext extends Context {
062:
063: /**
064: * This constant indicates interest in the named object only.
065: */
066: public static final int OBJECT_SCOPE = 0;
067:
068: /**
069: * This constant indicates interest in objects bound in the named context,
070: * but not the context itself.
071: */
072: public static final int ONELEVEL_SCOPE = 1;
073:
074: /**
075: * This constant indicates interest in the named object and its subtree.
076: * <p>
077: * When the named object is not a context, "subtree" here refers to the
078: * subtree of the context that contains the bound object. Where the named
079: * object is itself a context, "subtree" refers to the subtree of the named
080: * context.
081: * </p>
082: */
083: public static final int SUBTREE_SCOPE = 2;
084:
085: /**
086: * Registers <code>namingListener</code> for events concerning
087: * <code>name</code>, with scope <code>i</code>.
088: * <p>
089: * The scope must be one of <code>OBJECT_SCOPE</code>,
090: * <code>NELEVEL_SCOPE</code>, or <code>SUBTREE_SCOPE</code>.
091: * </p>
092: * <p>
093: * When the scope is <code>ONELEVEL_SCOPE</code>, <code>name</code>
094: * must be a context. Otherwise <code>name</code> can be a context or a
095: * bound object.
096: * </p>
097: * <p>
098: * Name is relative to this context.
099: * </p>
100: *
101: * @param name
102: * the concerning name
103: * @param i
104: * the scope
105: * @param namingListener
106: * the listener to be registered
107: * @throws NamingException
108: * If any exception occured.
109: */
110: void addNamingListener(Name name, int i,
111: NamingListener namingListener) throws NamingException;
112:
113: /**
114: * Registers <code>namingListener</code> for events concerning name, with
115: * scope <code>i</code>.
116: *
117: * @param s
118: * the concerning name string
119: * @param i
120: * the scope
121: * @param namingListener
122: * the listener to be registered
123: * @throws NamingException
124: * If any exception occured.
125: * @see #addNamingListener(Name, int, NamingListener)
126: */
127: void addNamingListener(String s, int i,
128: NamingListener namingListener) throws NamingException;
129:
130: /**
131: * Removes all registrations for <code>namingListener</code> in this
132: * <code>EventContext</code>. If there are no registrations this method
133: * does nothing.
134: *
135: * @param namingListener
136: * the listener to be unregistered
137: * @throws NamingException
138: * If any exception occured.
139: */
140: void removeNamingListener(NamingListener namingListener)
141: throws NamingException;
142:
143: /**
144: * Checks if the implementation supports registration for names that are not
145: * (yet) bound in this context.
146: *
147: * @return false if implementation supports this, otherwise true if the
148: * implementation does not support this.
149: * @throws NamingException
150: * If the support is not known.
151: */
152: boolean targetMustExist() throws NamingException;
153:
154: }
|