Jaffa Naming Conventions

1. Contents
   1. Contents
   2. Overview
   3. General
   4. Java Objects
      1. Java Code
      2. JSP's
      3. Tag Libraries
      4. Properties Files
      5. HTML / Web
   5. DTD's and XML Documents
      1. DTD File Names
      2. Pattern Generator Descriptors
      3. Runtime Descriptors
   6. Configuration Files
      1. ApplicationResources.properties
      2. General Properties Files
   7. Application Specific
      1. Business Functions
      2. Roles
      3. Components

2. Overview

   This is a guide to the naming standards used throughout Jaffa, and applications

   1. Conventions

      Title Case: - The first letter of each internal word capitalized
      e.g. UserId

      Lower Case: - All lower case

      e.g. userid

      Mixed Case: - The first letter lowercase and the first letter of each internal word capitalized.

      e.g. getUserId

      Lower Case Hyphenated: - All lower case, with a hyphen (-) separating words

      e.g. user-id

      Upper Case: - All upper case, with underscore (_) separating words

      e.g. USER_ID

      Note: Acronyms that are typically treated as a series of upper case letters are considered in the above context to be a 'word' (for example MILS, WIP, etc). There are some exceptions in core Java like URL, which have not been treated this way. Examples of this in Title Case would be MilsRequestInquiry, SupplierWipMove.

3. General

   The file name extensions listed below should be used where appropriate, and should all be lower case unless specified.

   Extension	Usage
   java	Java source files
   jsp	Java Sever Pages
   html	Static Web Page Content
   jar	Java Archive Files (binary)
   war	Web Archive Files (binary)
   xml	XML files used for various configuration data
   properties	Text files used for various configuration data
   gif	Image Files
   jpg	Image Files
   js	Java Script files
   css	Cascading Style Sheet files
   tld	JSP Tag Library Definitions
   zip	ZIP Compressed file sets
   dtd	Document Type Definitions For describing XML file structures
   xsd	XML Schemas For describing XML file structures

4. Java Objects

   1. Java Code

      Identifier	Standard	Example
      Package	Lower Case	com.spirentsystems.applications
      Class	Title Case	DataTranslator
      Method	Mixed Case	checkComponentAccess
      Constants	Upper Case	static final int MIN_WIDTH=4;
      Class Variables (static)	Mixed Case, prefixed with 'c_'	static HashMap c_formatMap;
      Member Variables (in class)	Mixed Case, prefixed with 'm_'	float m_myWidth = 1.0;
      Local Variables (in methods)	Mixed Case	int myLoop = 0;

   2. JSP's

      Identifier	Standard	Example
      JSP Folder	Lower Case	myapp/sample/jsp
      JSP Name	Mixed Case	pageExpired.jsp
      HTML Tags	Lower Case	<a href='xx'>
      Namespace	Title Case	<Widget:Label key='xx'/>

   3. Tag Libraries

      Identifier	Standard	Example
      Tag Name	Title Case	UserGrid
      Attribute Name	Mixed Case	useGuard

   4. Properties Files

      Identifier	Standard	Example
      File Name	Mixed Case	framework.properties, jaffaFramework.properties

   5. HTML / Web

      Identifier	Standard	Example
      Image File Name	Mixed Case	bottomLeftCorner.gifcorporateLogo16Colors.jpg
      JavaScript File Name	Mixed Case	calendarPopUp.js
      Folder Names	Lower Case	myapp/core/mycomponent/

      Note: JavaScript variable and method names should conform to the method and variable naming conventions as used by Java source code.

      Note: In terms of Jaffa Widgets there is a strict widget based naming convention for java script method names and html class names to prevent naming conflicts

      Note: With button images, when using the 'rollover' graphics, we typically use the convention <name>u.gif and <name>d.gif where 'u' implies the up (normal) state, and 'd' implies the down (selected) state.

5. DTD's and XML Documents

   1. DTD File Names

      We use the 'lower case hyphenated' convention for DTD filenames. It is also mandatory to include a version and sub-version number in the file name (this are separated with underscores).

      Once a DTD is release (put in the public domain), it is possible to update it if it has no impact on existing XML files. For example adding a new optional element. Any amendment that will cause already existing XML document to be invalidated must increase either the minor or major version number. Typically only the current and two prior versions of any DTD will be supported.

      Example Name: component-definition_1_0.dtd

   2. Pattern Generator Descriptors

      The reason this standard differs from the Runtime Descriptor standard, is that the XML files and their elements are translated into named objects and manipulated by WebMacro. WebMacro does not support variables with hyphenated names. For this reason any XML descriptor that is utilized by the pattern engine must use this format.

      Identifier	Standard	Example
      Element Names	Title Case	MappingPackage
      Attribute Names	Mixed Case	labelKey

   3. Runtime Descriptors

      This standard is modeled on the various deployment descriptors in the J2EE specifications for deployment descriptors like ejb-jar.xml, web.xml, etc.

      Identifier	Standard	Example
      Element Names	Lower Case Hypenated	grant-function-access
      Attribute Names	Lower Case Hypenated	base-package

6. Configuration Files

   1. ApplicationResources.properties

      This file contains all text that can vary in the application. It is intended to put all text in here that may need to change per deployment. All error messages, field labels and page titles are typically put in here. Display text that will only vary by language can be left in the JSP's if you expect to have JSP variants per language. If you don't want to do this put ALL text in this resource file.

      We use the following 4 types of resource name

      • error - Error messages that may contain other tokens and parameters
      • label - Field and Column labels, these may contain other tokens (if accessed by the 'Label' widget)
      • title - Screen titles, similar to labels
      • exception - Similar to error, but used for specific messages for a given ApplicationException class

      error, label and title, where possible follow the additional convention of <type>.<app name>.<module name>, for example

      error.MyApp.Wip.AdditionalInfoForm.LocationMandatory
      label.MyApp.Request.QuantityRequested
      title.MyApp.Contract.SegCodeLookup.results
      

      Further for labels that are modeling the fields of the domain objects the following convention is used label.<app name>.<module name>.<domain object>.<field>, for example

      label.MyApp.Printing.PrinterDefinition.PrinterClass=Printer
      label.MyApp.Printing.PrinterDefinition.Model1=Model
      label.MyApp.Printing.PrinterDefinition.Location=Location
      

      exception messages are based on following format exception.<exception class name>.<error token>, for example

      exception.org.jaffa.exceptions.DomainObjectNotFoundException.domainObjectNotFound={0} not found.
      exception.org.jaffa.exceptions.MandatoryFieldException.mandatoryField=Field {0} is mandatory.
      

   2. General Properties Files

      Typically a key is split into many segments, each segment is normally based on the 'Lower Case' format. It is also a standard in properties files that are used to configure system features, that there is a preceding comprehensive description, with example settings where applicable.

      Examples in framework.properties

      # Decides if Security-Check should be peformed framework.security.portlet.enabled=true # A comma-separated list of Actions for which security-check will not be performed # This is the setting, if you are using Application Authentication #framework.security.portlet.bypassActionList=/user_preLogon,/user_logon # This is the setting, if you are using Web Container Authentication framework.security.portlet.bypassActionList= # The default html fragment used by the Presentation for guarded buttons, relative to the classpath framework.presentation.defaultGuardedHtml.location=resources/html/defaultGuardedFragment.html

   3. Other Conventions

      In places where properties contain URL's (or URI's) that must comply with the [protocol]:[host]:[port]/[location] format we end the property name with ".url" for example

      • framework.widgets.usergrid.default.url
      • framework.widgets.usergrid.user.url

7. Application Specific

   1. Business Functions

      The naming convention we are using is based on 'Title Case' with the format of ., with a convention for controlling access to various domain objects we are using the convention .., where access type is typically one of Inquiry, Details or Maintenance.

      Example

      <business-function name="DataSecurity.SegCodeProfile.Inquiry"> <description>Able to view SegCode Profile</description> </business-function> <business-function name="DataSecurity.SegCodeProfile.Details"> <description>Able to view SegCode Profile Details</description> </business-function> <business-function name="DataSecurity.SegCodeProfile.Maintenance"> <description>Able to Create/Maintain Data Security SegCode Profile</description> </business-function>

   2. Roles

      Typically the Role Names are based on 'Title Case' and relate to the names on the High-Level Use Case model.

      Example

      <role name="User"> <description>This is a User. Every other user needs to inherit from this User</description> <grant-function-access name="Catalog.Part.Inquiry"/> <grant-function-access name="Catalog.Part.Details"/> </role> <role name="InternalUser"> <description>This is an Internal User</description> <grant-function-access name="DataSecurity.SegCodeProfile.Inquiry"/> <grant-function-access name="DataSecurity.SegCodeProfile.Details"/> </role>

   3. Components

      Typically the component names are based on 'Title Case' with the naming convention of ., where the component name typically resembles the name of the use case it is derived from.

      Example

      <component id="DataSecurity.CreateSegCodeProfile"> <class>org.myapp.datasecurity.createsegcodeprofile.ui.CreateSegCodeProfileComponent</class> <type>Skeleton</type> <mandatory-function name="DataSecurity.SegCodeProfile.Maintenance"/> </component> <component id="DataSecurity.SegCodeProfileFinder"> <class>org.myapp.datasecurity.segcodeprofilefinder.ui.SegCodeProfileFinderComponent</class> <type>ObjectFinder</type> <mandatory-function name="DataSecurity.SegCodeProfile.Inquiry"/> <mandatory-function name="DataSecurity.SegCodeProfile.Details"/> </component> <component id="DataSecurity.SegCodeProfileLookup"> <class>org.myapp.datasecurity.segcodeprofilelookup.ui.SegCodeProfileLookupComponent</class> <type>ObjectLookup</type> </component> <component id="DataSecurity.SegCodeProfileViewer"> <class>org.myapp.datasecurity.segcodeprofileviewer.ui.SegCodeProfileViewerComponent</class> <type>ObjectViewer</type> <mandatory-function name="DataSecurity.SegCodeProfile.Details"/> </component>