1 /*
2 * Copyright (C) 2013 4th Line GmbH, Switzerland
3 *
4 * The contents of this file are subject to the terms of either the GNU
5 * Lesser General Public License Version 2 or later ("LGPL") or the
6 * Common Development and Distribution License Version 1 or later
7 * ("CDDL") (collectively, the "License"). You may not use this file
8 * except in compliance with the License. See LICENSE.txt for more
9 * information.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 */
15
16 package org.fourthline.cling.registry;
17
18 import org.fourthline.cling.model.meta.LocalDevice;
19 import org.fourthline.cling.model.meta.RemoteDevice;
20
21 /**
22 * Notification of discovered device additions, removals, updates.
23 * <p>
24 * Add an instance of this interface to the registry to be notified when a device is
25 * discovered on your UPnP network, or when it is updated, or when it disappears.
26 * </p>
27 * <p>
28 * Implementations will be called concurrently by several threads, they should be thread-safe.
29 * </p>
30 * <p>
31 * Listener methods are called in a separate thread, so you can execute
32 * expensive procedures without spawning a new thread. The {@link #beforeShutdown(Registry)}
33 * and {@link #afterShutdown()} methods are however called in the thread that is stopping
34 * the registry and should not be blocking, unless you want to delay the shutdown procedure.
35 * </p>
36 *
37 * @author Christian Bauer
38 */
39 public interface RegistryListener {
40
41 /**
42 * Called as soon as possible after a device has been discovered.
43 * <p>
44 * This method will be called after SSDP notification datagrams of a new alive
45 * UPnP device have been received and processed. The announced device XML descriptor
46 * will be retrieved and parsed. The given {@link org.fourthline.cling.model.meta.RemoteDevice} metadata
47 * is validated and partial {@link org.fourthline.cling.model.meta.Service} metadata is available. The
48 * services are unhydrated, they have no actions or state variable metadata because the
49 * service descriptors of the device model have not been retrieved at this point.
50 * </p>
51 * <p>
52 * You typically do not use this method on a regular machine, this is an optimization
53 * for slower UPnP hosts (such as Android handsets).
54 * </p>
55 *
56 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
57 * @param device A validated and hydrated device metadata graph, with anemic service metadata.
58 */
59 public void remoteDeviceDiscoveryStarted(Registry registry, RemoteDevice device);
60
61 /**
62 * Called when service metadata couldn't be initialized.
63 * <p>
64 * If you override the {@link #remoteDeviceDiscoveryStarted(Registry, org.fourthline.cling.model.meta.RemoteDevice)}
65 * method, you might want to override this method as well.
66 * </p>
67 *
68 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
69 * @param device A validated and hydrated device metadata graph, with anemic service metadata.
70 * @param ex The reason why service metadata could not be initialized, or <code>null</code> if service
71 * descriptors couldn't be retrieved at all.
72 */
73 public void remoteDeviceDiscoveryFailed(Registry registry, RemoteDevice device, Exception ex);
74
75 /**
76 * Called when complete metadata of a newly discovered device is available.
77 *
78 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
79 * @param device A validated and hydrated device metadata graph, with complete service metadata.
80 */
81 public void remoteDeviceAdded(Registry registry, RemoteDevice device);
82
83 /**
84 * Called when a discovered device's expiration timestamp is updated.
85 * <p>
86 * This is a signal that a device is still alive and you typically don't have to react to this
87 * event. You will be notified when a device disappears through timeout.
88 * </p>
89 *
90 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
91 * @param device A validated and hydrated device metadata graph, with complete service metadata.
92 */
93 public void remoteDeviceUpdated(Registry registry, RemoteDevice device);
94
95 /**
96 * Called when a previously discovered device disappears.
97 * <p>
98 * This method will also be called when a discovered device did not update its expiration timeout
99 * and has been been removed automatically by the local registry. This method will not be called
100 * when the UPnP stack is shutting down.
101 * </p>
102 *
103 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
104 * @param device A validated and hydrated device metadata graph, with complete service metadata.
105 */
106 public void remoteDeviceRemoved(Registry registry, RemoteDevice device);
107
108 /**
109 * Called after you add your own device to the {@link org.fourthline.cling.registry.Registry}.
110 *
111 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
112 * @param device The local device added to the {@link org.fourthline.cling.registry.Registry}.
113 */
114 public void localDeviceAdded(Registry registry, LocalDevice device);
115
116 /**
117 * Called after you remove your own device from the {@link org.fourthline.cling.registry.Registry}.
118 * <p>
119 * This method will not be called when the UPnP stack is shutting down.
120 * </p>
121 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
122 * @param device The local device removed from the {@link org.fourthline.cling.registry.Registry}.
123 */
124 public void localDeviceRemoved(Registry registry, LocalDevice device);
125
126 /**
127 * Called after registry maintenance stops but before the registry is cleared.
128 * <p>
129 * This method should typically not block, it executes in the thread that shuts down the UPnP stack.
130 * </p>
131 * @param registry The Cling registry of all devices and services know to the local UPnP stack.
132 */
133 public void beforeShutdown(Registry registry);
134
135 /**
136 * Called after the registry has been cleared on shutdown.
137 * <p>
138 * This method should typically not block, it executes in the thread that shuts down the UPnP stack.
139 * </p>
140 */
141 public void afterShutdown();
142
143 }