: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.




== Usage

There are two mixins that will contribute to this interface:

* xref:refguide:applib:index/services/bookmark/BookmarkHolder_lookup.adoc[BookmarkHolder_lookup]
+
which contributes a `lookup` action to return the referenced object

* xref:refguide:applib:index/services/bookmark/BookmarkHolder_object.adoc[BookmarkHolder_object]
+
which contributes instead an `object` property, being the referenced object.

Either of these can be suppressed, if required, using a xref:userguide:btb:hints-and-tips.adoc#vetoing-visibility[vetoing subscriber] that listens to the action or property domain event in order to hide the member.

== Examples

For example, a `Customer` object with an xref:refguide:applib:index/annotation/DomainObject.adoc#logicalTypeName[logical type name] of "custmgmt.Customer" and an id of 123 would correspond to a xref:index/services/bookmark/Bookmark.adoc[Bookmark] with a string representation of "custmgmt.Customer|123".

Bookmarks are useful to store a reference to an arbitrary object, although be aware that there is no referential integrity.

Several of the extension libraries use bookmarks.
For example the xref:refguide:applib:index/services/publishing/spi/EntityPropertyChangeSubscriber.adoc[EntityPropertyChangeSubscriber] uses bookmarks to identify the object that is being modified.

Serialized form of bookmarks also appear within  xref:refguide:schema:about.adoc[schema] instances, for example as used by xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] and the xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber].

== See Also

* xref:refguide:applib:index/services/bookmark/Bookmark.adoc[Bookmark]
* xref:refguide:applib:index/services/bookmark/BookmarkHolder.adoc[BookmarkHolder]

