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.
For detailed information about the code convension for Java Server Pages TM , see Code Convention for Java Server Pages TM .

1. 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> PetStoreEAR</display-name>

or (in case of conflict):

<display-name> BluePrintsPetStoreEAR</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:

    1. jms/QueueConnectionFactory
    2. jms/TopicConnectionFactory
    3. jms/RemoteConnectionFactory
    4. 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.


Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
JavaOne Banner Java 8 banner (182)