Java 持久性的命名约定

状态:在 Early Access 版本阶段
作者:Sean Brydon 及 Smitha Kangath

问题描述

阅读其他人编写的代码可能是很困难的,尤其是较大的项目。开发者可能具有其自己的风格,并且在命名类、对象和资源等方面可能具有其自己的选择。这使其他人更难以阅读他们的代码,并且很难使用或维护这些代码。再者,这可能会导致同一团队中的开发者争论哪种选择更好的问题,从而造成不必要的麻烦。

解决方案

命名约定可以使代码更易于阅读,以便其他人能够更好地理解代码。命名约定还可以提供有关标识符预期功能的信息。本文介绍了 Java BluePrints 团队用于其样例应用程序的命名约定。这些约定适用于 Java EE 5 平台中的各种组件和模块。通过应用这些约定,将更易于标识和组织模块和组件,因而改进了它们的维护,并有助于在较大项目中进行更好的协调。

此处介绍的所有约定与 Java 编程语言的代码约定相一致。

要注意的一点是,很多内容使用缺省的标注设置。例如,将实体对象映射到数据库表时,缺省设置是表名与对象名相同。因此,如果实体 Bean 的名称为 Customer,则不需要使用 @Table(name=CUSTOMER) 标注的 name 属性将其映射到数据库中的 customer 表。因此,命名约定需要考虑以下情况:标注使用很多缺省名称来简化编码。也就是说,您需要注意一些隐式命名。我们建议您遵循标注命名约定的所有缺省设置,因为通过这样做,您可以为标注编写较少的代码,而仅依靠缺省设置即可。

还要注意,SQL 和 Java 查询语言中包含很多保留字。在使用这些保留字时,需要特别小心。

现在,我们介绍一些标识符类型及其关联的命名约定。我们首先尝试遵循用于 Java 持久性规范 (JSR 220) 中的样例的约定。

标识符类型

命名规则

示例和参考

实体(标注为 @Entity) 只使用对象的名称。
不要附加 "Bean" 或 "POJO" 后缀。
遵循类的命名约定

例如,Address.java 是一个地址实体的名称。
实体管理器工厂(标注为 @PersitenceUnit) 如果只有一个实体管理器工厂,则名称是 emf

如果有多个实体管理器工厂,则命名规则是向名称附加 "Emf",例如 <持久性单元名称>Emf 

例如,
public EntityManagerFactory emf;

如果有多个实体管理器工厂,
public EntityManagerFactory pestoreEmf;
public EntityManagerFactory inventoryWarehouseEmf;
实体管理器(标注为 @PersistenceContext) 如果只有一个实体管理器,则名称是 em

如果有多个实体管理器,则向名称附加 "Em"。通常,实体管理器与持久性单元密切相关,因此,常用约定为 <持久性单元名称>Em

例如,
private EntityManager em;


如果有多个实体管理器,
private EntityManager pestoreEm;
private EntityManager inventoryWarehouseEm;
用户事务 utx 是要使用的名称

例如,
public UserTransaction utx;
侦听程序(标注为 @EntityListeners) 规则是向实体名称附加 "Listener"
例如,
OrderListener
持久性单元
应该基于资源名称。资源名称应该带有 "Pu" 后缀。应该以混合大小写的形式编写资源名称,并且将每个词的第一个字母大写
<资源名称>Pu
例如,在 persistence.xml 文件中

<persistence>
    <persistence-unit name="PetstorePu">
        <jta-data-source>jdbc/PetstoreDB</jta-data-source>
    </persistence-unit>
</persistence>

数据源名称

应该基于资源名称。应该以混合大小写的形式编写资源名称,并且将每个词的第一个字母大写
jdbc/<资源名称>


示例:
jdbc/PetStoreDB
O/R 映射文件

如果要在源代码中覆盖 O/R 映射标注,请使用此文件。
当每个 META_INF/persistence.xml 只需要一个映射文件时,请使用缺省名称 orm.xml

当需要多个映射文件时,请使用 <资源名称>Orm.xml

例如,
<persistence>
    <persistence-unit name="PetstorePu">
        <jta-data-source>jdbc/PetstoreDB</jta-data-source>
        <mapping-file>orm.xml<mapping-file>
          ...
    </persistence-unit>
</persistence>

<persistence>
    <persistence-unit name="InventoryWarehousePu">
        <jta-data-source>jdbc/OrdersDB</jta-data-source>
        <mapping-file>orderOrm.xml<mapping-file>
          ...
    </persistence-unit>
</persistence>

命名查询和 finder 方法
采用混合大小写的形式,第一个字母小写,并将每个内部词的第一个字母大写。

必须指定命名查询的范围,我们使用类名作为范围。
例如,此命名查询中的 "getItemsPerProductCategory"
@NamedQuery(
name="getItemsPerProductCategory",
query="SELECT i FROM Item i WHERE i.product.categoryId LIKE :categoryName"
)
public class MyEntity { ...

而在使用命名查询的查询中,应按如下方式指定命名查询的范围并进行使用
Query query =
 em.createNamedQuery("MyEntity.getItemsPerProductCategory")
命名参数 采用混合大小写的形式,第一个字母小写,并将每个内部词的第一个字母大写。
在 Java 查询语言中,可以指定可传入到查询中的命名参数。命名查询也会使用这些命名参数。
例如,参数 ":categoryName"
query =
 em.createQuery("
SELECT i FROM Item i WHERE i.product.categoryId LIKE :categoryName");
query = query.setParameter("
categoryName", "dogs");
数据库

如果您的组织已制订了数据库命名约定,请遵循该约定。否则,应按照应用程序来命名数据库并附加 DB。

<应用程序名称>DB

例如:PetStoreDB

数据库命名约定和 Java 命名约定

在命名实体对象时,实体名称通常与关联数据库表的名称类似。但数据库命名约定与 Java 命名约定略有不同。例如,在数据库中,表通常是复数形式,例如,CUSTOMERS 表。而在对象命名约定中,映射的对象通常具有单数名称,例如,Customer。在这种情况下,您需要将映射信息放在 Customer 实体的实体标注的 CUSTOMERS 中。由于这是通常的做法,因此,我们将其视为备选约定,但它要求每个实体类使用表标注将实体映射到表上,例如,Customer 实体的 @Table(name=CUSTOMERS) 标注。

在 Java 持久性中提供了缺省映射。例如,缺省设置是表名具有与对象名相同的名称。因此,Customer 实体将缺省映射到 CUSTOMER 表上,并且不需要使用标注。将对象及其关联的表命名为相同名称并只使用缺省映射是非常方便的。由于这是 Java 持久性中的缺省命名,并且是一项易于使用的功能,因此,我们也使用这种约定。

参考资料

以下是一些参考资料:

© Sun Microsystems 2006。Java BluePrints Solutions Catalog 中的所有内容受版权保护,未经 Sun Microsystems 的明确书面许可,不得在其他产品中发布。