GlassFish - World's first Java EE 7 Application Server


GlassFish Documentation Style Sheet

The purpose of the style sheet is to help people who are writing or editing material for this release to maintain consistency across the documentation. Here's where we keep track of special spellings, terminology, capitalization, trademarking, and acronyms commonly used in this documentation set.

For general editorial style guidelines, see Documentation Style Guide for OpenSolaris (PDF).

Use the following abbreviations to help clarify how the term should be used: (n) noun, (v) verb, (adj) adjective. If you add terms to this list, please add them in alphabetical order.

ABC

  • annotate (v) - do not use decorate.
  • annotation (n)
  • add-on component (n,adj) not plugin, not module
  • (the) Administration Console(n,adj) referring to the graphical console
  • Admin Console, GUI--Don't use. Use the Administration Console.
  • Administration Console online help
  • Administration Server. Don't use. See DAS.
  • application server(n,adj) referring to a generic application server
  • application server instance. Don't use. See server instance.
  • Application Server Management eXtension (AMX)
  • (the) asadmin utility, example of referring to a utility
  • (the) asadmin list --user adminuser command when referring to a command
  • CLI. Don't use. Instead use the asadmin (or command-line) utility, the asadmin commands, or command-line as an adjective.
  • client-side(adj)
  • command-line(adj) for example, command-line interface
  • command line (n) for example, on the command line
  • Common Object Request Broker Architecture (CORBA)
  • container managed persistence (CMP)

DEF

  • Derby. Do not use. See Java DB.
  • decorate. Do not use. See annotate.
  • diagnostic service(n,adj)
  • Document Type Definition (DTD)
  • (the) domain administration server (DAS)
  • (the) domain.xml file, example of referring to a file
  • EJB. See TradeMarked Terms below.
  • enterprise archive (EAR)
  • Enterprise Server(n,adj), not the Enterprise Server; referring to Prelude product name (formerly Application Server)

GHI

  • GlassFish. See Trademarked Terms below. Use uppercase F - GlassFish not Glassfish. See also version.
  • gem (n). Note lack of capitals.
  • high availability(n,adj)
  • Hundred-Kilobyte Kernel (HK2)
  • (the) High Availability Database (HADB)
  • host (n,adj) referring to a physical machine
  • install(v), installation(n,adj)
  • Internet Inter-ORB Protocol (IIOP)

JK

  • Java. See Trademarked Terms below.
  • Java APIs for XML processing (JAXP)
  • Java APIs for XML registries (JAXR)
  • Java APIs for remote procedure calls (JAX-RPC)
  • Java archive (JAR) (adj), a JAR file
  • Java Authorization Contract for Containers (JACC)
  • Java Business Integration (JBI)
  • (the) Java DB database(n,adj), replaces Derby
  • Java Data Base Connectivity (JDBC)
  • Java Message Service (JMS)
  • JavaMail
  • Java Monitoring and Management Console (jConsole)
  • Java Naming and Directory Interface (JNDI)
  • Java Secure Socket Extension (JSSE)
  • Java servlet
  • JSP. See Trademarked Terms below.
  • JVM. On first usage: Virtual Machine for the Java(tm) platform (Java Virtual Machine or JVM(tm) machine). See also Trademarked Terms below.
  • JRuby-on-Rails

LMN

  • lifecycle(n,adj)
  • machine. Don't use. See host.
  • man page, not manpage(n,adj)
  • managed bean (MBean)
  • node(n,adj) referring to software, such as node agent
  • Network Security Services (NSS)

OPQR

  • Object Request Broker (ORB)
  • open-source (adj). For example: open-source software.
  • OSGi bundle - note the lowercase "i". Also note that OSGi is not an initialism and so no expanded form of it exists. In other wores, there is no definition.
  • plain old java object (POJO)
  • plug in (v) two words - acceptable for describing the act of plugging in an add-on component
  • plugin (n) Don't use if referring to add-on component for GlassFish.
  • Production Web Container (PWC)
  • Red Hat (2 words, initial capitals)
  • Remote Method Invocation (RMI)

ST

  • Secure Sockets Layer (SSL)
  • server-side(adj)
  • server instance not application server instance
  • service-oriented architecture (SOA)
  • setup(n), set up(v)
  • Simple Oject Access Protocol (SOAP)
  • Simple Mail Transfer Protocol (SMTP)
  • SOAP with Attachments API for Java (SAAJ)
  • system(n,adj) referring to a collection of software and hardware

UVW

  • update release. Use UR# (UR1) not Update 1 or Update Release 1
  • Universal Description, Discover, and Integration (UDDI)
  • Update Tool (n, adj) not the Update Tool
  • version of product. Use lowercase v, not spelled out (GlassFish v3) not GlassFish V3 or GlassFish version 3
  • web application(n,adj)
  • web archive (WAR) (adj), a WAR file
  • web module(n,adj)
  • web service(n,adj)
  • Web Services Description Language (WSDL)

XYX Numbers

  • eXtensible Markup Language (XML)

Trademarked Terms

Enterprise JavaBeanstm (EJBtm) Can be used as EJB(adj) after first usage.
GlassFish(tm) project
Java(tm)
JavaServer Pages (JSPtm)
JVM(tm): On first usage: Virtual Machine for the Java(tm) platform (Java Virtual Machine or JVM(tm) machine) Can be used as JVM(adj) after first usage.
MySQL(tm) database

Special Font Conventions

The following should be rendered in monospace font: file names, program names, command names, environment variables, parameters, code samples.

Variables (replaceables) should be rendered as italic, without brackets.

Abbreviations and Short Names

GlassFish v3 Enterprise Server can be referred to as Enterprise Server after first usage.
High Availability Database can be referred to as HADB after first usage.
Java DB database can be referred as Java DB after first usage

Path Variable Conventions

The path variables listed in the Default Paths and File Names section of the standard preface should be used consistently in all documents.

DO NOT list the domain root directory as as-install/domains or as-install/domain-root-dir unless you are describing a specific operating system and version that you know has this structure. The domain root is NOT under the installation directory in several operating systems.

Incorrect alternatives to as-install are very common and should be corrected. Here is a non-exhaustive list: install, $INSTALL, <install>, <install>, <INSTALL>, installdir, installdir, INSTALLDIR, $INSTALLDIR, <installdir>, <installdir>, <INSTALLDIR>, <$INSTALLDIR>, install-dir, install-dir, INSTALL-DIR, $INSTALL-DIR, <install-dir>, <install-dir>, <INSTALL-DIR>, <$INSTALL-DIR>, install_dir, install_dir, INSTALL_DIR, $INSTALL_DIR, <install_dir>, <install_dir>, <INSTALL_DIR>, <$INSTALL_DIR>, install-root, install-root, INSTALL-ROOT, $INSTALL-ROOT, <install-root>, <install-root>, <INSTALL-ROOT>, <$INSTALL-ROOT>, install_root, install_root, INSTALL_ROOT, $INSTALL_ROOT, <install_root>, <install_root>, <INSTALL_ROOT>, <$INSTALL_ROOT>, as-install, <as-install>, appserver-install, appserver-install, <appserver-install>, AS_HOME, $AS_HOME, $AS91_HOME, as91_home, as91-home, server-root, server-root, <server-root>, <server-root>, SERVER-ROOT, $SERVER-ROOT, <SERVER-ROOT>, <$SERVER-ROOT>, server_root, server_root, <server_root>, <server_root>, SERVER_ROOT, $SERVER_ROOT, <SERVER_ROOT>, <$SERVER_ROOT>, etc.

Why are so many examples included in this still non-exhaustive list, when just a few would make the point? Because all of these have appeared in the docs. Such "variety" is potentially very confusing to readers.

Miscellaneous