Guidelines, Patterns, and code for end-to-end Java applications

Naming Conventions for Enterprise Applications Early Access 2

This document describes the naming conventions that the BluePrints team uses for its sample applications. These conventions pertain to the various components and modules in the Java 2 Platform, Enterprise Edition (J2EE). By applying these conventions, your modules and components will be easier to identify and organize, thus enhancing their maintenance and promoting better coordination on large projects.

All conventions described here are compliant to Code Conventions for the Java Programming Language.

J2EE Application, Module, and Component Names

This includes the archive names and the display names in the deployment descriptors for a  J2EE application and the different J2EE modules and also the base name for a J2EE component. A J2EE application is packaged as an Enterprise ARchive (EAR) file with a .ear extension. Enterprise JavaBeans modules are packaged as JAR  files with a .jar extension. Web modules are packaged as JAR files with a .war (Web ARchive) extension.

Description References in the Code Conventions
Application Name The application name is used as the application archive name. By default, the application name should be indicative of the application and should be written in all-lowercase ASCII letters. In case of conflict, the application name should be a more specific and descriptive version:

Application archive: <application-name> .ear

Example:

petstore.ear // enterprise archive

or (in case of conflict):

bppetstore.ear // enterprise archive

The application display name (in the application deployment descriptor) is the expanded 1 application name written in mixed cases:

<expanded-application-name> EAR

Example:

<display-name> PetStore EAR</display-name>

or (in case of conflict):

<display-name> BluePrintsPetStore EAR</display-name>

Follows naming conventions for packages
Enterprise JavaBeans (EJB) Module Name The module name is used as the EJB archive name. By default, the module name should be based on the package name and should be written in all-lowercase ASCII letters. In case of conflict, the module name should be a more specific version (including other part of the package name):

EJB archive: <module-name> -ejb.jar

EJB client archive: <module-name> -ejb-client.jar

Example:

com.sun.j2ee.blueprints. petstore petstore-ejb.jar // EJB archive petstore-ejb-client.jar // EJB client archive

or (in case of conflict):

bppetstore-ejb.jar // EJB archive bppetstore-ejb-client.jar // EJB client archive

The module display name (in the EJB deployment descriptor) is the expanded module name written in mixed cases:

<expanded-module-name> JAR

Example:

<display-name> PetStoreJAR</display-name>

or (in case of conflict):

<display-name> BluePrintsPetStoreJAR</display-name>

Follows naming conventions for packages

Web Module Name The module name is used as the web archive name. By default, the module name should be based on the package name and should be written in all-lowercase ASCII letters. In case of conflict, the module name should be a more specific version (including other part of the package name):

Web archive: <module-name> .war

Applet client archive: <module-name> -applet-client.jar

Midlet client archive: <module-name>

Application client archive: <module-name> -app-client.jar

Example:

com.sun.j2ee.blueprints. petstore petstore.war // Web archive petstore-applet-client.jar // Applet archive

or (in case of conflict):

bppetstore.war // Web archive

bppetstore-applet-client.jar // Applet archive

The module display name (in the Web deployment descriptor) is the expanded module name written in mixed cases:

<expanded-module-name> WAR

Example:

<display-name> PetStoreWAR</display-name>

or (in case of conflict):

<display-name> BluePrintsPetStoreWAR</display-name>

Follows naming conventions for packages
Component Name The component is the base name of the EJB or web component class name and should be written in mixed case with the first letter of each internal word capitalized.

Example:

PopulateServlet

ContactInfoBean

Follows naming conventions for classes

2. EJB Component Names

This includes naming conventions for the different parts of an enterprise bean. Wherever these names go in the deployment descriptor, it has been specified. The conventions listed here does not mention the type of the bean explicitly, except for the display name in the deployment descriptor.

Description

References in the Code Conventions
Entity Bean Local interface: <component-name> or <component-name> Local

Local home interface: <component-name> Home or <component-name> LocalHome

Remote interface: <component-name> Remote

Remote home interface: <component-name> RemoteHome

Implementation class: <component-name> Bean

Primary key implementation:

<component-name> PK

Abstract schema:

<component-name>

Name in the EJB deployment descriptor: <component-name> Bean

Display name in the EJB deployment descriptor:

<expanded-component-name> EB

Follows naming conventions for classes
Session Bean Local interface: <component-name> or <component-name> Local

Local home interface: <component-name> Home or <component-name> LocalHome

Remote interface: <component-name> Remote

Remote home interface: <component-name> RemoteHome

Implementation class: <component-name> Bean

Name in the EJB deployment descriptor: <component-name> Bean

Display name in the EJB deployment descriptor: <expanded-component-name> SB

Follows naming conventions for classes
Message Driven Bean Implementation class: <component-name> Bean

Name in the deployment descriptor: <component-name> Bean

Display name in the EJB deployment descriptor: <expanded-component-name> MDB

Follows naming conventions for classes

3. Web Component Names

This includes naming conventions for  Servlets and  JavaServer Pages TM  and their related artifacts like Servlet filters and JavaServer Pages TM tags

Description

References in the Code Conventions
Servlet Implementation class: <component-name> Servlet

Name in the Web deployment descriptor: component-name

Display name in the Web deployment descriptor: <expanded-component-name> Servlet

Follows naming conventions for classes

Filter Implementation: <component-name> Filter

Name in the Web deployment descriptor: component-name

Display name in the Web deployment descriptor: <expanded-component-name> Filter

Follows naming conventions for classes

Listener For classes implement following listener interfaces: 
javax.servlet.ServletContextListener
                  
javax.servlet.ServletContextAttributeListener
                    
javax.servlet.HttpSessionListener
                    
javax.servlet.HttpSessionAttributeListener
                     
javax.servlet.ServletRequestListener
                    
javax.servlet.ServletRequestAttributeListener
, the convention is:

Implementation: <component-name> Listener

Name in the Web deployment descriptor: component-name

Display name in the Web deployment descriptor: <expanded-component-name> Listener

Follows naming conventions for classes

JavaServer Pages TM JSP (file) name should always begin with a lower-case letter. The name may consists of multiple words, in which case the words are placed immediately adjacent and each word commences with an upper-case letter. A JSP name can be just a simple noun or a short sentence. A verb-only JSP name should be avoided, as it does not convey sufficient information to developers.

Example: performLogin.jsp

Here're conventions for other file types.

  • JSP Segments: /WEB-INF/jspf/ file .jspf
  • JSP Documents in XML syntax: file .jspx
  • Tag Files: /WEB-INF/tags/[../] file .tag
  • Tag file in XML syntax: /WEB-INF/tags/[../] file .tagx
  • TLD: /WEB-INF/tlds/ file .tld
Follows Code Convention for the Java Server Pages
JavaServer Pages TM Tag Names
  • Tag extra information

  • Implementation: <component-name> TEI

  • Tag library validator

  • Implementation: <component-name> TLV

  • Tag handler interface

  • Implementation: <component-name> Tag

  • Tag handler implementation

  • Implementation: <component-name> Tag

Follows Code Convention for the Java Server Pages

4. Web service Names

This includes naming conventions for Web service clients and endpoints and the necessary configuration files.

Description

References in the Code Conventions
Service Name The service name is the base name of the EJB or JAX-RPC endpoint class name and should be written in mixed case with the first letter of each internal word capitalized.

Example:

WeatherService

Follows naming conventions for classes
EJB service endpoint Service endpoint interface : <service-name> SEI

Service implementation class : <service-name> Bean

Follows naming conventions for classes
JAX-RPC service  endpoint Service endpoint interface : <service-name> SEI

Service implementation class : <service-name> Impl

Follows naming conventions for classes
JAX-RPC message  handler Client side handler : <service-name> ClientHandler

Server side handler : <service-name> ServerHandler

Follows naming conventions for classes
Configuration  files WSDL file  :  <service-name>

Example:

WeatherService.wsdl

JAX-RPC mapping file  : <all-lower-case -service-name > -mapping

Example:

weatherservice-mapping.xml

wscompile configuration file  : <all-lower-case-service-name> -config

Example:

weatherservice-config.xml

wscompile configuration file for client : <all-lower-case-service-name> -client-config

Example:

weatherservice-client-config.xml

5. Reference Names

EJB reference name is the logical name you use in your source code for a JNDI lookup of the home interface of  the referenced bean. This name also apperas  as the value of the ejb-ref-name element within the ejb-ref element in the deployment decriptor of the referencing component.

Web service reference name is the name used by Web service clients for a JNDI lookup to obtain a reference to a Web service. This name also apperas as the value of the service-ref-name element within the service-ref element in the deployment decriptor of the referencing component.

Resource reference name and resource environment reference name are used by components for a JNDI lookup of the connection factories and resources. The referencing component also declares these names in its deployment decriptor . Resource reference name apperas  as the value of the res-ref-name element within the resource-ref element in the deployment decriptor . Resource environment reference name appears as the value of the resource-env-ref-name element within the resource-env-ref element

  Environment entry names are the names used by a component for a JNDI lookup of some customizable parameters.  T his name also apperas  as the value of the env-entry-name  element within the env-entry element in the deployment decriptor of the component.

All the reference names are relative to java:comp/env.

Description References in the Code Conventions
EJB References By default, the EJB reference name should be based on the component name. The component name should be written in mixed case with the first letter of each internal word capitalized

ejb/ <component-name> [Local|Remote]

If you have only the local or the remote interface, you may want to use just ejb/ <component-name> and leave out the suffixes. If you have both kind of interfaces, you may want to use the suffix only for the remote interfaces since typically you will have fewer of them.

In case of conflict, the EJB reference name should be a more specific version of the component name.

Example:

Say you have a Customer EJB module ( customer-ejb.jar) which contains the ContactInfoBean component ( ContactInfoBean.class). In this case, the Customer module will refer to the ContactInfo module in the following way:

ejb/ContactInfo

In case, the Customer module had two ContactInfo objects: one for customer, and one for supplier; the names will be:

ejb/CustomerContactInfo ejb/SupplierContactInfo

Follows naming conventions for classes

Web service references The Web service reference name should be based on the service name. The service name should be written in mixed case with the first letter of each internal word capitalized

service/ <service-name>

Example:

service/CreditCardService

Resource References

The resource  reference name should be based on the resource name. The resource name should be written in mixed case with the first letter of each internal word capitalized

jms/ <resource-name> [Queue|Topic] Examples:

  1. jms/InvoiceTopic
  2. jms/PurchaseOrderQueue

    jdbc/ <resource-name> Examples:

    1. jdbc/PetStoreDB
    2. jdbc/CatalogDB

    url/ <resource-name>

    eis/ <resource-name>

    mail/ < resource-qualifier Example:

    1. mail/MailSession

    jms/ <resource-qualifier> Factory or jms/ <resource-qualifier> [Queue|Topic]Factory Examples:

    jms/QueueConnectionFactory

    jms/TopicConnectionFactory

    jms/RemoteConnectionFactory

    jms/DurableConnectionFactory or jms/DurableTopicConnectionFactory. You need a connection factory with a client id in order to use durable subscriptions

Environment Entries

The paramter name should be written in mixed case with the first letter of each internal word capitalized. Parameters may be grouped under a common context name.

param/ <parameter-name>

param [ / <context-name>]* / <parameter-name>

Example:

param/CatalogDAOClass param/event/ActionEvent

6. Database Names

This applies to the databases that map to CMP entity beans. This convention does not apply when you are mapping CMP entities to a prexisting schema, since the database entities already have names.

Description

References in the Code Conventions
Database If your organization already has a convention for database naming, follow that. Otherwise, name CMP databases after the application.

For example: PetStore DB

7. XML Document Names

Description References in the Code Conventions
XML Documents One possible notation:

Element names follow the code convention of class names and should be written in mixed case with the first letter of each internal word capitalized.

Attribute names follow the code convention of variable names and should be written in mixed case with a lower case first letter.

Enumerated Attribute values follow the code convention of constants and should be written in upper case with words seperated by underscores.

Example:

< CreditCard type=' VISA'> </ CreditCard>

Another possible notation:

Element names are written in lower case with words separeted by a hyphen '-'.

Attribute names follow the code convention of variable names and should be written in mixed case with a lower case first letter.

Enumerated attribute values follow the code convention of constants and should be written in upper case with words seperated by underscores.

Example:

< credit-card type=' VISA'> </ credit-card>

Any other notation as long as it is consistent across your application

Follows Classes, Variable, Constant

8. Deployment Descriptor Names

Description References in the Code Conventions

Deployment Descriptors 2

J2EE application deployment descriptor: application.xml

J2EE application client deployment descriptor: application-client.xml

Web services deployment descriptor: webservices.xml

EJB deployment descriptor: ejb-jar.xml or <module-name> -ejb-jar.xml

Sun Java System Application Server specific EJB deployment descriptor: sun-ejb-jar.xml

Web deployment descriptor: web.xml or <module-name> -ejb-jar.xml

Sun Java System Application Server specific Web deployment descriptor: sun-web.xml

Manifest file for the J2EE application client archive: application-client-manifest.mf or <module-name>- application-client-manifest.mf

Manifest file for the EJB archive: ejb-jar-manifest.mf or <module-name> -ejb-jar-manifest.mf

1 All abbreviations expanded, like “OrderProcessingCenter” for OPC.

2 Note that these file names are not the actual names that exist in the jar files. The actual names are fixed as per relevant specifications. For example, all the manifest files are named as MANIFEST.MF and placed in the META-INF/ directory inside the jar files. The names application-client-manifest.mf or ejb-jar-manifest.mf are prototype names that help in distinguishing them from each other when they are placed in the same source directory.