Summary
-------

Define a lightweight network protocol for discovering running and
manageable Java processes within a network subnet.


Goals
-----

  - A simple service that does not have dependencies on anything other
    than what is in the JDK.

  - A service that does not require any process other than the Java
    process to run.

  - It must be able to provide information about a running Java process
    on the network, and it must be possible to detect when the Java
    process is no longer running.

  - It must not require prior knowledge about what machines are available
    on the network.

  - It must include information about the endpoint of communication, such
    as the JMXService URL.

  - The service should be stopped when we stop the management agent and
    it should not be possible to start the service without the management
    agent.

  - It should contain other information useful for rendering the
    connection in a client, such as PID, JRE version, and main class.

  - It should be possible to extend the information broadcasted.


Non-Goals
---------

  - The protocol is not intended to be used across a public network.

  - The protocol doesn't offer any access control; that should be done in
    the network layer.


Description
-----------

The protocol is lightweight multicast based, and works like a beacon,
broadcasting the JMXService URL needed to connect to the external JMX
agent if an application is started with appropriate parameters.

The payload is structured like this:

    4 bytes JDP magic (0xC0FFEE42)
    2 bytes JDP protocol version (1)
    2 bytes	size of the next entry
        x bytes next entry (UTF-8 encoded)
        2 bytes size of next entry
    ...	Rinse and repeat...

The payload will be parsed as even entries being keys, odd entries being
values.

The standard JDP packet contains four entries:

  - `DISCOVERABLE_SESSION_UUID` -- Unique id of the instance; this id changes every time
    the discovery protocol starts and stops

  - `MAIN_CLASS` -- The value of the `sun.java.command` property

  - `JMX_SERVICE_URL` -- The URL to connect to the JMX agent

  - `INSTANCE_NAME` -- The user-provided name of the running instance

The protocol uses system properties to control its behaviour:

  - `com.sun.management.jdp.port` -- override default port

  - `com.sun.management.jdp.address` -- override default address

  - `com.sun.management.jmxremote.autodiscovery` -- whether we should start autodiscovery or
    not. Autodiscovery starts if and only if following conditions are met: (autodiscovery is
    true OR (autodiscovery is not set AND jdp.port is set))

  - `com.sun.management.jdp.ttl`         -- set ttl for broadcast packet, default is 1

  - `com.sun.management.jdp.pause`       -- set broadcast interval in seconds default is 5

  - `com.sun.management.jdp.source_addr` -- an address of interface to use for broadcast

### Default values

ticket [IANA #656814]:

224.0.23.178  JDP Java Discovery Protocol

ticket [IANA #656816]

7095/UDP

Testing
-------

Unit tests will be provided.


Impact
------

  - Other JDK components: Will only impact the JMX Agent

  - Compatibility: No impact

  - Security: The protocol is off by default, also the default TTL for
    multicast packets is set to zero so the packet will not escape a
    local network.

  - Performance/scalability: Limited impact, one extra thread

  - User experience: No impact

  - I18n/L10n: No impact

  - Accessibility: No impact

  - Portability: No impact

  - Packaging/installation: No impact

  - Documentation: The new options and their usage will have to be
    documented.

  - TCK: No impact