1 // Copyright 2003-2005 Arthur van Hoff, Rick Blair
2 // Licensed under Apache License version 2.0
3 // Original license LGPL
4 package javax.jmdns;
5
6 import java.net.Inet4Address;
7 import java.net.Inet6Address;
8 import java.net.InetAddress;
9 import java.util.Enumeration;
10 import java.util.Map;
11
12 import javax.jmdns.impl.ServiceInfoImpl;
13
14 /**
15 * <p>
16 * The fully qualified service name is build using up to 5 components with the following structure:
17 *
18 * <pre>
19 * <app>.<protocol>.<servicedomain>.<parentdomain>.<br/>
20 * <Instance>.<app>.<protocol>.<servicedomain>.<parentdomain>.<br/>
21 * <sub>._sub.<app>.<protocol>.<servicedomain>.<parentdomain>.
22 * </pre>
23 *
24 * <ol>
25 * <li><servicedomain>.<parentdomain>: This is the domain scope of the service typically "local.", but this can also be something similar to "in-addr.arpa." or "ip6.arpa."</li>
26 * <li><protocol>: This is either "_tcp" or "_udp"</li>
27 * <li><app>: This define the application protocol. Typical example are "_http", "_ftp", etc.</li>
28 * <li><Instance>: This is the service name</li>
29 * <li><sub>: This is the subtype for the application protocol</li>
30 * </ol>
31 * </p>
32 */
33 public abstract class ServiceInfo implements Cloneable {
34
35 /**
36 * This is the no value text byte. According top the specification it is one byte with 0 value.
37 */
38 public static final byte[] NO_VALUE = new byte[0];
39
40 /**
41 * Fields for the fully qualified map.
42 */
43 public enum Fields {
44 /**
45 * Domain Field.
46 */
47 Domain,
48 /**
49 * Protocol Field.
50 */
51 Protocol,
52 /**
53 * Application Field.
54 */
55 Application,
56 /**
57 * Instance Field.
58 */
59 Instance,
60 /**
61 * Subtype Field.
62 */
63 Subtype
64 }
65
66 /**
67 * Construct a service description for registering with JmDNS.
68 *
69 * @param type
70 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
71 * @param name
72 * unqualified service instance name, such as <code>foobar</code>
73 * @param port
74 * the local port on which the service runs
75 * @param text
76 * string describing the service
77 * @return new service info
78 */
79 public static ServiceInfo create(final String type, final String name, final int port, final String text) {
80 return new ServiceInfoImpl(type, name, "", port, 0, 0, false, text);
81 }
82
83 /**
84 * Construct a service description for registering with JmDNS.
85 *
86 * @param type
87 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
88 * @param name
89 * unqualified service instance name, such as <code>foobar</code>
90 * @param subtype
91 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
92 * @param port
93 * the local port on which the service runs
94 * @param text
95 * string describing the service
96 * @return new service info
97 */
98 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final String text) {
99 return new ServiceInfoImpl(type, name, subtype, port, 0, 0, false, text);
100 }
101
102 /**
103 * Construct a service description for registering with JmDNS.
104 *
105 * @param type
106 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
107 * @param name
108 * unqualified service instance name, such as <code>foobar</code>
109 * @param port
110 * the local port on which the service runs
111 * @param weight
112 * weight of the service
113 * @param priority
114 * priority of the service
115 * @param text
116 * string describing the service
117 * @return new service info
118 */
119 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final String text) {
120 return new ServiceInfoImpl(type, name, "", port, weight, priority, false, text);
121 }
122
123 /**
124 * Construct a service description for registering with JmDNS.
125 *
126 * @param type
127 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
128 * @param name
129 * unqualified service instance name, such as <code>foobar</code>
130 * @param subtype
131 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
132 * @param port
133 * the local port on which the service runs
134 * @param weight
135 * weight of the service
136 * @param priority
137 * priority of the service
138 * @param text
139 * string describing the service
140 * @return new service info
141 */
142 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final String text) {
143 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false, text);
144 }
145
146 /**
147 * Construct a service description for registering with JmDNS. The properties hashtable must map property names to either Strings or byte arrays describing the property values.
148 *
149 * @param type
150 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
151 * @param name
152 * unqualified service instance name, such as <code>foobar</code>
153 * @param port
154 * the local port on which the service runs
155 * @param weight
156 * weight of the service
157 * @param priority
158 * priority of the service
159 * @param props
160 * properties describing the service
161 * @return new service info
162 */
163 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final Map<String, ?> props) {
164 return new ServiceInfoImpl(type, name, "", port, weight, priority, false, props);
165 }
166
167 /**
168 * Construct a service description for registering with JmDNS. The properties hashtable must map property names to either Strings or byte arrays describing the property values.
169 *
170 * @param type
171 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
172 * @param name
173 * unqualified service instance name, such as <code>foobar</code>
174 * @param subtype
175 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
176 * @param port
177 * the local port on which the service runs
178 * @param weight
179 * weight of the service
180 * @param priority
181 * priority of the service
182 * @param props
183 * properties describing the service
184 * @return new service info
185 */
186 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final Map<String, ?> props) {
187 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false, props);
188 }
189
190 /**
191 * Construct a service description for registering with JmDNS.
192 *
193 * @param type
194 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
195 * @param name
196 * unqualified service instance name, such as <code>foobar</code>
197 * @param port
198 * the local port on which the service runs
199 * @param weight
200 * weight of the service
201 * @param priority
202 * priority of the service
203 * @param text
204 * bytes describing the service
205 * @return new service info
206 */
207 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final byte[] text) {
208 return new ServiceInfoImpl(type, name, "", port, weight, priority, false, text);
209 }
210
211 /**
212 * Construct a service description for registering with JmDNS.
213 *
214 * @param type
215 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
216 * @param name
217 * unqualified service instance name, such as <code>foobar</code>
218 * @param subtype
219 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
220 * @param port
221 * the local port on which the service runs
222 * @param weight
223 * weight of the service
224 * @param priority
225 * priority of the service
226 * @param text
227 * bytes describing the service
228 * @return new service info
229 */
230 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final byte[] text) {
231 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false, text);
232 }
233
234 /**
235 * Construct a service description for registering with JmDNS.
236 *
237 * @param type
238 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
239 * @param name
240 * unqualified service instance name, such as <code>foobar</code>
241 * @param port
242 * the local port on which the service runs
243 * @param weight
244 * weight of the service
245 * @param priority
246 * priority of the service
247 * @param persistent
248 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
249 * @param text
250 * string describing the service
251 * @return new service info
252 */
253 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final boolean persistent, final String text) {
254 return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent, text);
255 }
256
257 /**
258 * Construct a service description for registering with JmDNS.
259 *
260 * @param type
261 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
262 * @param name
263 * unqualified service instance name, such as <code>foobar</code>
264 * @param subtype
265 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
266 * @param port
267 * the local port on which the service runs
268 * @param weight
269 * weight of the service
270 * @param priority
271 * priority of the service
272 * @param persistent
273 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
274 * @param text
275 * string describing the service
276 * @return new service info
277 */
278 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final boolean persistent, final String text) {
279 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, persistent, text);
280 }
281
282 /**
283 * Construct a service description for registering with JmDNS. The properties hashtable must map property names to either Strings or byte arrays describing the property values.
284 *
285 * @param type
286 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
287 * @param name
288 * unqualified service instance name, such as <code>foobar</code>
289 * @param port
290 * the local port on which the service runs
291 * @param weight
292 * weight of the service
293 * @param priority
294 * priority of the service
295 * @param persistent
296 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
297 * @param props
298 * properties describing the service
299 * @return new service info
300 */
301 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final boolean persistent, final Map<String, ?> props) {
302 return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent, props);
303 }
304
305 /**
306 * Construct a service description for registering with JmDNS. The properties hashtable must map property names to either Strings or byte arrays describing the property values.
307 *
308 * @param type
309 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
310 * @param name
311 * unqualified service instance name, such as <code>foobar</code>
312 * @param subtype
313 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
314 * @param port
315 * the local port on which the service runs
316 * @param weight
317 * weight of the service
318 * @param priority
319 * priority of the service
320 * @param persistent
321 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
322 * @param props
323 * properties describing the service
324 * @return new service info
325 */
326 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final boolean persistent, final Map<String, ?> props) {
327 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, persistent, props);
328 }
329
330 /**
331 * Construct a service description for registering with JmDNS.
332 *
333 * @param type
334 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
335 * @param name
336 * unqualified service instance name, such as <code>foobar</code>
337 * @param port
338 * the local port on which the service runs
339 * @param weight
340 * weight of the service
341 * @param priority
342 * priority of the service
343 * @param persistent
344 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
345 * @param text
346 * bytes describing the service
347 * @return new service info
348 */
349 public static ServiceInfo create(final String type, final String name, final int port, final int weight, final int priority, final boolean persistent, final byte[] text) {
350 return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent, text);
351 }
352
353 /**
354 * Construct a service description for registering with JmDNS.
355 *
356 * @param type
357 * fully qualified service type name, such as <code>_http._tcp.local.</code>.
358 * @param name
359 * unqualified service instance name, such as <code>foobar</code>
360 * @param subtype
361 * service subtype see draft-cheshire-dnsext-dns-sd-06.txt chapter 7.1 Selective Instance Enumeration
362 * @param port
363 * the local port on which the service runs
364 * @param weight
365 * weight of the service
366 * @param priority
367 * priority of the service
368 * @param persistent
369 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
370 * @param text
371 * bytes describing the service
372 * @return new service info
373 */
374 public static ServiceInfo create(final String type, final String name, final String subtype, final int port, final int weight, final int priority, final boolean persistent, final byte[] text) {
375 return new ServiceInfoImpl(type, name, subtype, port, weight, priority, persistent, text);
376 }
377
378 /**
379 * Construct a service description for registering with JmDNS. The properties hashtable must map property names to either Strings or byte arrays describing the property values.
380 *
381 * @param qualifiedNameMap
382 * dictionary of values to build the fully qualified service name. Mandatory keys are Application and Instance. The Domain default is local, the Protocol default is tcp and the subtype default is none.
383 * @param port
384 * the local port on which the service runs
385 * @param weight
386 * weight of the service
387 * @param priority
388 * priority of the service
389 * @param persistent
390 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
391 * @param props
392 * properties describing the service
393 * @return new service info
394 */
395 public static ServiceInfo create(final Map<Fields, String> qualifiedNameMap, final int port, final int weight, final int priority, final boolean persistent, final Map<String, ?> props) {
396 return new ServiceInfoImpl(qualifiedNameMap, port, weight, priority, persistent, props);
397 }
398
399 /**
400 * Returns true if the service info is filled with data.
401 *
402 * @return <code>true</code> if the service info has data, <code>false</code> otherwise.
403 */
404 public abstract boolean hasData();
405
406 /**
407 * Fully qualified service type name, such as <code>_http._tcp.local.</code>
408 *
409 * @return service type name
410 */
411 public abstract String getType();
412
413 /**
414 * Fully qualified service type name with the subtype if appropriate, such as <code>_printer._sub._http._tcp.local.</code>
415 *
416 * @return service type name
417 */
418 public abstract String getTypeWithSubtype();
419
420 /**
421 * Unqualified service instance name, such as <code>foobar</code> .
422 *
423 * @return service name
424 */
425 public abstract String getName();
426
427 /**
428 * The key is used to retrieve service info in hash tables.<br/>
429 * The key is the lower case qualified name.
430 *
431 * @return the key
432 */
433 public abstract String getKey();
434
435 /**
436 * Fully qualified service name, such as <code>foobar._http._tcp.local.</code> .
437 *
438 * @return qualified service name
439 */
440 public abstract String getQualifiedName();
441
442 /**
443 * Get the name of the server.
444 *
445 * @return server name
446 */
447 public abstract String getServer();
448
449 /**
450 * Returns the host IP address string in textual presentation.<br/>
451 * <b>Note:</b> This can be either an IPv4 or an IPv6 representation.
452 *
453 * @return the host raw IP address in a string format.
454 * @deprecated since 3.2.3
455 * @see #getHostAddresses()
456 */
457 @Deprecated
458 public abstract String getHostAddress();
459
460 /**
461 * Returns the host IP addresses string in textual presentation.
462 *
463 * @return list of host raw IP address in a string format.
464 */
465 public abstract String[] getHostAddresses();
466
467 /**
468 * Get the host address of the service.<br/>
469 *
470 * @return host Internet address
471 * @deprecated since 3.1.8
472 * @see #getInetAddresses()
473 */
474 @Deprecated
475 public abstract InetAddress getAddress();
476
477 /**
478 * Get the InetAddress of the service. This will return the IPv4 if it exist, otherwise it return the IPv6 if set.<br/>
479 * <b>Note:</b> This return null if the service IP address cannot be resolved.
480 *
481 * @return Internet address
482 * @deprecated since 3.2.3
483 * @see #getInetAddresses()
484 */
485 @Deprecated
486 public abstract InetAddress getInetAddress();
487
488 /**
489 * Get the IPv4 InetAddress of the service.<br/>
490 * <b>Note:</b> This return null if the service IPv4 address cannot be resolved.
491 *
492 * @return Internet address
493 * @deprecated since 3.2.3
494 * @see #getInet4Addresses()
495 */
496 @Deprecated
497 public abstract Inet4Address getInet4Address();
498
499 /**
500 * Get the IPv6 InetAddress of the service.<br/>
501 * <b>Note:</b> This return null if the service IPv6 address cannot be resolved.
502 *
503 * @return Internet address
504 * @deprecated since 3.2.3
505 * @see #getInet6Addresses()
506 */
507 @Deprecated
508 public abstract Inet6Address getInet6Address();
509
510 /**
511 * Returns a list of all InetAddresses that can be used for this service.
512 * <p>
513 * In a multi-homed environment service info can be associated with more than one address.
514 * </p>
515 *
516 * @return list of InetAddress objects
517 */
518 public abstract InetAddress[] getInetAddresses();
519
520 /**
521 * Returns a list of all IPv4 InetAddresses that can be used for this service.
522 * <p>
523 * In a multi-homed environment service info can be associated with more than one address.
524 * </p>
525 *
526 * @return list of InetAddress objects
527 */
528 public abstract Inet4Address[] getInet4Addresses();
529
530 /**
531 * Returns a list of all IPv6 InetAddresses that can be used for this service.
532 * <p>
533 * In a multi-homed environment service info can be associated with more than one address.
534 * </p>
535 *
536 * @return list of InetAddress objects
537 */
538 public abstract Inet6Address[] getInet6Addresses();
539
540 /**
541 * Get the port for the service.
542 *
543 * @return service port
544 */
545 public abstract int getPort();
546
547 /**
548 * Get the priority of the service.
549 *
550 * @return service priority
551 */
552 public abstract int getPriority();
553
554 /**
555 * Get the weight of the service.
556 *
557 * @return service weight
558 */
559 public abstract int getWeight();
560
561 /**
562 * Get the text for the service as raw bytes.
563 *
564 * @return raw service text
565 */
566 public abstract byte[] getTextBytes();
567
568 /**
569 * Get the text for the service. This will interpret the text bytes as a UTF8 encoded string. Will return null if the bytes are not a valid UTF8 encoded string.<br/>
570 * <b>Note:</b> Do not use. This method make the assumption that the TXT record is one string. This is false. The TXT record is a series of key value pairs.
571 *
572 * @return service text
573 * @see #getPropertyNames()
574 * @see #getPropertyBytes(String)
575 * @see #getPropertyString(String)
576 * @deprecated since 3.1.7
577 */
578 @Deprecated
579 public abstract String getTextString();
580
581 /**
582 * Get the URL for this service. An http URL is created by combining the address, port, and path properties.
583 *
584 * @return service URL
585 * @deprecated since 3.2.3
586 * @see #getURLs()
587 */
588 @Deprecated
589 public abstract String getURL();
590
591 /**
592 * Get the list of URL for this service. An http URL is created by combining the address, port, and path properties.
593 *
594 * @return list of service URL
595 */
596 public abstract String[] getURLs();
597
598 /**
599 * Get the URL for this service. An URL is created by combining the protocol, address, port, and path properties.
600 *
601 * @param protocol
602 * requested protocol
603 * @return service URL
604 * @deprecated since 3.2.3
605 * @see #getURLs()
606 */
607 @Deprecated
608 public abstract String getURL(String protocol);
609
610 /**
611 * Get the list of URL for this service. An URL is created by combining the protocol, address, port, and path properties.
612 *
613 * @param protocol
614 * requested protocol
615 * @return list of service URL
616 */
617 public abstract String[] getURLs(String protocol);
618
619 /**
620 * Get a property of the service. This involves decoding the text bytes into a property list. Returns null if the property is not found or the text data could not be decoded correctly.
621 *
622 * @param name
623 * property name
624 * @return raw property text
625 */
626 public abstract byte[] getPropertyBytes(final String name);
627
628 /**
629 * Get a property of the service. This involves decoding the text bytes into a property list. Returns null if the property is not found, the text data could not be decoded correctly, or the resulting bytes are not a valid UTF8 string.
630 *
631 * @param name
632 * property name
633 * @return property text
634 */
635 public abstract String getPropertyString(final String name);
636
637 /**
638 * Enumeration of the property names.
639 *
640 * @return property name enumeration
641 */
642 public abstract Enumeration<String> getPropertyNames();
643
644 /**
645 * Returns a description of the service info suitable for printing.
646 *
647 * @return service info description
648 */
649 public abstract String getNiceTextString();
650
651 /**
652 * Set the text for the service. Setting the text will fore a re-announce of the service.
653 *
654 * @param text
655 * the raw byte representation of the text field.
656 * @exception IllegalStateException
657 * if attempting to set the text for a non persistent service info.
658 */
659 public abstract void setText(final byte[] text) throws IllegalStateException;
660
661 /**
662 * Set the text for the service. Setting the text will fore a re-announce of the service.
663 *
664 * @param props
665 * a key=value map that will be encoded into raw bytes.
666 * @exception IllegalStateException
667 * if attempting to set the text for a non persistent service info.
668 */
669 public abstract void setText(final Map<String, ?> props) throws IllegalStateException;
670
671 /**
672 * Returns <code>true</code> if ServiceListener.resolveService will be called whenever new new information is received.
673 *
674 * @return the persistent
675 */
676 public abstract boolean isPersistent();
677
678 /**
679 * Returns the domain of the service info suitable for printing.
680 *
681 * @return service domain
682 */
683 public abstract String getDomain();
684
685 /**
686 * Returns the protocol of the service info suitable for printing.
687 *
688 * @return service protocol
689 */
690 public abstract String getProtocol();
691
692 /**
693 * Returns the application of the service info suitable for printing.
694 *
695 * @return service application
696 */
697 public abstract String getApplication();
698
699 /**
700 * Returns the sub type of the service info suitable for printing.
701 *
702 * @return service sub type
703 */
704 public abstract String getSubtype();
705
706 /**
707 * Returns a dictionary of the fully qualified name component of this service.
708 *
709 * @return dictionary of the fully qualified name components
710 */
711 public abstract Map<Fields, String> getQualifiedNameMap();
712
713 /*
714 * (non-Javadoc)
715 * @see java.lang.Object#clone()
716 */
717 @Override
718 public ServiceInfo clone() {
719 try {
720 return (ServiceInfo) super.clone();
721 } catch (CloneNotSupportedException exception) {
722 // clone is supported
723 return null;
724 }
725 }
726
727 }