< prev index next >
src/java.naming/share/classes/javax/naming/event/EventContext.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 1999, 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
--- 1,7 ----
/*
! * Copyright (c) 1999, 2019, 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
*** 32,42 ****
/**
* Contains methods for registering/deregistering listeners to be notified of
* events fired when objects named in a context changes.
*
! *<h1>Target</h1>
* The name parameter in the {@code addNamingListener()} methods is referred
* to as the <em>target</em>. The target, along with the scope, identify
* the object(s) that the listener is interested in.
* It is possible to register interest in a target that does not exist, but
* there might be limitations in the extent to which this can be
--- 32,42 ----
/**
* Contains methods for registering/deregistering listeners to be notified of
* events fired when objects named in a context changes.
*
! *<h2>Target</h2>
* The name parameter in the {@code addNamingListener()} methods is referred
* to as the <em>target</em>. The target, along with the scope, identify
* the object(s) that the listener is interested in.
* It is possible to register interest in a target that does not exist, but
* there might be limitations in the extent to which this can be
*** 57,67 ****
*<p>
* An application can use the method {@code targetMustExist()} to check
* whether an {@code EventContext} supports registration
* of nonexistent targets.
*
! *<h1>Event Source</h1>
* The {@code EventContext} instance on which you invoke the
* registration methods is the <em>event source</em> of the events that are
* (potentially) generated.
* The source is <em>not necessarily</em> the object named by the target.
* Only when the target is the empty name is the object named by the target
--- 57,67 ----
*<p>
* An application can use the method {@code targetMustExist()} to check
* whether an {@code EventContext} supports registration
* of nonexistent targets.
*
! *<h2>Event Source</h2>
* The {@code EventContext} instance on which you invoke the
* registration methods is the <em>event source</em> of the events that are
* (potentially) generated.
* The source is <em>not necessarily</em> the object named by the target.
* Only when the target is the empty name is the object named by the target
*** 91,101 ****
* keep a reference to the {@code EventContext} instance on
* which it invoked {@code addNamingListener()} (just as
* it needs to keep a reference to the listener in order to remove it
* later). It cannot expect to do a {@code lookup()} and get another instance of
* an {@code EventContext} on which to perform the deregistration.
! *<h1>Lifetime of Registration</h1>
* A registered listener becomes deregistered when:
*<ul>
*<li>It is removed using {@code removeNamingListener()}.
*<li>An exception is thrown while collecting information about the events.
* That is, when the listener receives a {@code NamingExceptionEvent}.
--- 91,101 ----
* keep a reference to the {@code EventContext} instance on
* which it invoked {@code addNamingListener()} (just as
* it needs to keep a reference to the listener in order to remove it
* later). It cannot expect to do a {@code lookup()} and get another instance of
* an {@code EventContext} on which to perform the deregistration.
! *<h2>Lifetime of Registration</h2>
* A registered listener becomes deregistered when:
*<ul>
*<li>It is removed using {@code removeNamingListener()}.
*<li>An exception is thrown while collecting information about the events.
* That is, when the listener receives a {@code NamingExceptionEvent}.
*** 103,113 ****
* instance with which it has registered.
</ul>
* Until that point, an {@code EventContext} instance that has outstanding
* listeners will continue to exist and be maintained by the service provider.
*
! *<h1>Listener Implementations</h1>
* The registration/deregistration methods accept an instance of
* {@code NamingListener}. There are subinterfaces of {@code NamingListener}
* for different of event types of {@code NamingEvent}.
* For example, the {@code ObjectChangeListener}
* interface is for the {@code NamingEvent.OBJECT_CHANGED} event type.
--- 103,113 ----
* instance with which it has registered.
</ul>
* Until that point, an {@code EventContext} instance that has outstanding
* listeners will continue to exist and be maintained by the service provider.
*
! *<h2>Listener Implementations</h2>
* The registration/deregistration methods accept an instance of
* {@code NamingListener}. There are subinterfaces of {@code NamingListener}
* for different of event types of {@code NamingEvent}.
* For example, the {@code ObjectChangeListener}
* interface is for the {@code NamingEvent.OBJECT_CHANGED} event type.
*** 116,126 ****
* single invocation of {@code addNamingListener()}.
* In addition to reducing the number of method calls and possibly the code size
* of the listeners, this allows some service providers to optimize the
* registration.
*
! *<h1>Threading Issues</h1>
*
* Like {@code Context} instances in general, instances of
* {@code EventContext} are not guaranteed to be thread-safe.
* Care must be taken when multiple threads are accessing the same
* {@code EventContext} concurrently.
--- 116,126 ----
* single invocation of {@code addNamingListener()}.
* In addition to reducing the number of method calls and possibly the code size
* of the listeners, this allows some service providers to optimize the
* registration.
*
! *<h2>Threading Issues</h2>
*
* Like {@code Context} instances in general, instances of
* {@code EventContext} are not guaranteed to be thread-safe.
* Care must be taken when multiple threads are accessing the same
* {@code EventContext} concurrently.
< prev index next >