=== Object aliases

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

The xref:refguide:applib:index/annotation/DomainObject.adoc#logicalTypeName[logicalTypeName()] element is used to provide a unique alias for the object's class name.

This value is used internally to generate a string representation of an objects identity (the `Oid`).
This can appear in several contexts, including:

* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
(see xref:refguide:applib:index/services/bookmark/BookmarkService.adoc[BookmarkService])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd.adoc[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
* in the URLs of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)]
* in XML snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[XmlSnapshotService]

== Examples

For example:

[source,java]
----
@DomainObject(
    logicalTypeName="orders.Order"
)
public class Order {
    ...
}
----

== Precedence

The rules of precedence are:

. `@DomainObject#logicalTypeName`
. ORM-specific:

.. JDO: xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable], if at least the `schema` attribute is defined.
+
If both `schema` and `table` are defined, then the value is "`schema.table`".
If only `schema` is defined, then the value is "`schema.className`".

.. (JPA) `@Table#schema()`.

. Fully qualified class name of the entity.

[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.

Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
At best this will require a data migration in the database; at worst it could cause external clients, eg if accessing data through the xref:vro:ROOT:about.adoc[Restful Objects] viewer, to break.
====

If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot.
An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
