Appendix F Web Server Interfaces

This appendix describes the interfaces in Web Server and their stability level. Sun products classify public interfaces according to their expected stability level so that you can make informed decisions when creating dependencies on these interfaces. For example, you can confidently create programmatic dependencies (for example, shell scripts) which rely on stable interfaces, knowing these will not change often (if ever).

Note that the word interface is used in a very broad sense. Any implementation detail on which your code might rely on can be an interface. This includes APIs but also includes aspects such as CLI option names, file system paths, file names and so forth.

In the following table, the stability levels have the following definitions:

Standard – Interfaces defined by a standard, for example Java Servlet API (JSR 154). Changes track the standard specification and are as stable as the referenced standard.
Stable – Incompatibilities are exceptional. Incompatible changes can only occur in the next major release and with prior warning. While possible, incompatible changes to stable interfaces are not expected.
Evolving – Incompatibilities are rare. Incompatible change can only occur in the next minor release and with prior warning.
Unstable – Experimental or transitional: incompatibilities are common. While future release of the Web Server might attempt to provide either stability or a migration path for unstable interfaces, incompatible changes are possible at any time. If at all possible, avoid creating programmatic dependencies on unstable interfaces or your code might break in a future release. If you need to create programmatic dependencies on unstable interfaces, structure your code in a way which makes it easy to adapt to future changes.
Obsolete – Obsolete interfaces continue to be supported but might be removed in some (not yet determined) future release. Do not create any new dependencies on obsolete interfaces. If you have existing dependencies on obsolete interfaces, remove those dependencies as soon as possible.
Private – Private interfaces cannot be relied on for any use. Private interfaces might change incompatibly (or disappear entirely) without prior notice at any time. Sun cannot provide any support or assurance of any use of private interfaces.

Note –
Private interfaces are for the most part not listed in this appendix, because all interfaces not documented in the product documentation are by default private. However, some visible but private interfaces are explicitly documented as private in this appendix to highlight the fact that these interfaces cannot be used.

Table F–1 Interfaces


Interface Name	Stability Level	Comments
`server.xml`	Unstable	Avoid creating scripts which read or write to `server.xml` directly. Instead, use the `wadm` CLI to reliably modify `server.xml`.
`magnus.conf`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`default.acl`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`certmap.conf`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`obj.conf`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`mime.types`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`server.policy`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`login.conf`	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
Any configuration files not specifically listed above	Private	Naming and contents of any other configuration files are not intended for user manipulation.
`$PKGROOT/bin/`	Stable	The location of supported public binaries.
`$PKGROOT/include/`	Stable	The location of public include files for developers.
`$PKGROOT/plugins/`	Stable	The location of documented plug-ins.
`$PKGROOT/samples/`	Unstable	Samples are a form of documentation. They are provided for reference, but might change from release to release. Do not build hard dependencies on samples.
`$PKGROOT/lib/`	Private	No external use supported.
`instance_dir/bin/*`	Stable	The location of supported, public, instance-specific binaries: `startserv`, `stopserv`, `rotate`, `restart`, and `reconfig`.
`instance_dir//logs/access`	Location: stable Content: stable	The access log file can be parsed by scripts.
`instance_dir//logs/errors`	Location: stable Content: not an Interface	The content of the log, for example, the wording of messages, is not an interface suitable for programmatic access and might change from patch to patch. It is intended for visual parsing by human readers only.
Installer CLI and options	Evolving
Uninstall CLI and options	Evolving
Silent installer statefile variables	Evolving
Installer graphical user interface (GUI)	Unstable	GUI screen layouts are generally unstable.
Installer exit values	Evolving
Configurator/unconfigurator back-end CLIs	Private	No external use supported.
Configurator back-end properties	Private	No external use supported.
Jacl	Private	No external use supported.
JLine	Private	No external use supported.
PCRE	Private	No external use supported.
Xalan C++	Private	No external use supported.
Xerces C++	Private	No external use supported.
schema2beans	Private	No external use supported.
Admin Console	Unstable	GUI screen layouts are generally unstable.
`wadm` CLI and command-line arguments	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`wadm` CLI error codes	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`wadm` password file format	Evolving	Where possible, use the `wadm` CLI to reliably modify configuration files.
`wadm` output (`stdout` and `stderr`)	Not an interface	Output generated by the CLI only provides messages for a human reader. It is not intended for programmatic parsing or scripting.
`.wadmrc` file	Evolving	Optional Jacl file residing in the user's home directory or loaded up by `--rcfile`. It serves as a startup file.
`wdeploy` CLI	Obsolete	Previously obsoleted, still retained. Replaced by `wadm`. Will be removed in a future release.
SNMP MIB	Evolving
JES-MF MBeans	Private	No external use supported.
com.sun.appserv.server.Lifecycle APIs	Evolving	API details in lifecycle spec.
JSR 88 implementation	Evolving
`SUNWwbsvr7` (Solaris) `sun-webserver-7.0.0-1.i386.rpm` (Linux rpm)	Stable	Main Web Server 7.0 package. The name will change in the next major release.
`SUNWwbsvr7-dev` (Solaris) `sun-webserver-dev-7.0.0-1.i386.rpm` (Linux rpm)	Stable	Package that contains additional files for developer support (for example, header files). The name will change in the next major release.
`SUNWwbsvr7-cli` (Solaris) `sun-webserver-cli-7.0.0-1.i386.rpm` (Linux rpm)	Stable	The CLI package. The CLI can be installed separately on other hosts. The name will change in the next major release.
N1 `plugin-descriptor.xml`	Private	No external use supported.
N1 `pluginUI.xml`	Private	No external use supported.
TCP port 8989	Stable	Default administration HTTP SSL port. IANA registration completed.
TCP port 8800	Stable	Default administration HTTP non-SSL port. IANA registration completed.
WebDAV	Standard	RFC 2518, RFC 3744.
JSTL 1.1	Standard
`MaxProcs` mode	Deprecated for Java technology-enabled servers