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
PagesTM, 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 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
<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 PagesTM
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 PagesTM
|
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 PagesTM 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. This 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:
jms/InvoiceTopicjms/PurchaseOrderQueue
jdbc/<resource-name>
Examples:
jdbc/PetStoreDBjdbc/CatalogDB
url/<resource-name>
eis/<resource-name>
mail/<resource-qualifier>
Example:
mail/MailSession
jms/<resource-qualifier>Factory
or jms/<resource-qualifier>[Queue|Topic]Factory
Examples:
jms/QueueConnectionFactoryjms/TopicConnectionFactoryjms/RemoteConnectionFactoryjms/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: PetStoreDB
|
|
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
|
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
|
|
Print-friendly Version
