Additional permission needed to run Derby network server

Symptoms Seen by Applications Affected by Change

An additional java.net.SocketPermission, "listen" was added to the default network server policy file, and the policy file template. The documentation was updated to describe this permission.

Incompatibilities with Previous Release

No incompatibilities arise from upgrading a Derby release to one with the additional permissions in the policy file.
However, unless you have this permission, when upgrading to a JVM release that has JDK 7u51 incorporated, your network server may not start if

Rationale for Change

An additional permission may be needed in order to bring up the Derby network server after upgrading to JVMs incorporating JDK 7u51. In particular, the startup scripts may fail to boot the network server.

This is a result of the "Better applet networking" changes made for JVM issue 8011787 (not public): the default socket permissions assigned to all code including untrusted code have been changed.
Previously, all code was able to bind any socket type to any port number greater than or equal to 1024. It is still possible to bind sockets to the ephemeral port range on each system. The exact range of ephemeral ports varies from one operating system to another, but it is typically in the high range (such as from 49152 to 65535).
The new restriction is that binding sockets outside of the ephemeral range now requires an explicit permission in the system security policy.

After upgrading to a JVM with these changes, while attempting to boot, the network server may fail and raise the following error:

access denied ("java.net.SocketPermission" "localhost:1527" "listen,resolve") java.security.AccessControlException: access denied ("java.net.SocketPermission" "localhost:1527" "listen,resolve")
To workaround this problem, you must bring up the network server with a security policy which includes the now required missing permission. Instead of booting the network server as:
java org.apache.derby.drda.NetworkServerControl start
boot the network server as follows:
java -Djava.security.manager -Djava.security.policy=${yourPolicyFile} org.apache.derby.drda.NetworkServerControl start
where ${yourPolicyFile} is a file containing a customized version of the policy file described in the Derby Admin Guide section titled Basic Network Server security policy. You must customize that generic policy file to fit your application. In addition, you must add the following permission to the permissions block granted to the ${derby.install.url}derbynet.jar codebase:
permission java.net.SocketPermission "localhost:${port}", "listen";
where ${port} should be replaced by the port number where the network server listens for incoming connection requests. By default, that is port 1527. 

For more information on Derby security policies, see the Derby Admin Guide sections titled Network Server security and Running the Network Server under the security manager.

If you are using replication, a similar permission must be granted to the security policy for the slave server. Add the following permission to the ${derby.install.url}derby.jar codebase:

permission java.net.SocketPermission "localhost:${slavePort}", "listen";
where ${slavePort} should be replaced by the port number where the slave server listens for incoming connection requests (typically 4851). For more information on the security policy for the slave server, see the Derby Admin Guide section titled Replication and security. 

With this fix, the default policy file has received these required permissions, and the scripts in the bin directory work again. However, it may still be necessary to adjust any customized policy files.

Application Changes Required

Applications need not make any change to take advantage of the new permission granted in the default policy file. However, the default policy file may, or may not be sufficient for specific applications and it is better to use your own policy file. If you have your own policy file, you may need to adjust it to add the "listen" permission as appropriate.