001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 */
019
020package org.apache.isis.core.metamodel.adapter.oid;
021
022import org.apache.isis.applib.services.bookmark.Bookmark;
023import org.apache.isis.core.metamodel.adapter.version.Version;
024import org.apache.isis.core.metamodel.spec.ObjectSpecification;
025import org.apache.isis.core.metamodel.spec.SpecificationLoaderSpi;
026
027
028/**
029 * Defines a subtype of {@link Oid} specific to a root adapter.
030 * 
031 * <p>
032 * The root adapter/pojo can be recreated with no further information; the
033 * {@link #getObjectSpecId()} can be used to fetch the corresponding
034 * {@link ObjectSpecification} using {@link SpecificationLoaderSpi#lookupBySpecId(String)}.
035 * 
036 * <p>
037 * <p>
038 * As such, is directly akin to the DSP's oid that is of the form 
039 * <tt>CUS|1234567A</tt>, where the overall form is a simple string
040 * and also identifies the type of the object.
041 *
042 * <p>
043 * In addition, can be directly encoded/decoded into strings.  The {@link #enString(OidMarshaller)} interface
044 * is defined in the interface; implementations must also provide a static 
045 * <tt>deString(String)</tt> factory method.
046 */
047public interface RootOid extends TypedOid {
048
049    String getIdentifier();
050    
051    void setVersion(Version version);
052
053
054    /**
055     * Returns a new RootOid for the same {@link #getObjectSpecId()}, but persistent and with the specified {@link #getIdentifier() identifier}.
056     */
057    RootOid asPersistent(String identifier);
058
059    /**
060     * The result of performing a {@link #compareTo(Comparison) comparison.}
061     */
062    public static enum Comparison {
063        /**
064         * The two {@link RootOid oid}s identify the same domain object,
065         * (meaning {@link RootOid#equals(Object) equals} method returns <tt>true</tt>)
066         * and the {@link RootOid#getVersion() version information} held within the 
067         * oid is the same.
068         */
069        EQUIVALENT_AND_UNCHANGED,
070        /**
071         * The two {@link RootOid oid}s identify the same domain object,
072         * (meaning {@link RootOid#equals(Object) equals} method returns <tt>true</tt>)
073         * but the {@link RootOid#getVersion() version information} held within the 
074         * oid is the different.
075         */
076        EQUIVALENT_BUT_CHANGED,
077        /**
078         * The two {@link RootOid oid}s identify the same domain object,
079         * (meaning {@link RootOid#equals(Object) equals} method returns <tt>true</tt>)
080         * but there is no {@link RootOid#getVersion() version information} so 
081         * cannot determine whether the domain object has changed.
082         */
083        EQUIVALENT_BUT_NO_VERSION_INFO,
084        /**
085         * The two {@link RootOid oid}s identify the different domain objects,
086         * (meaning {@link RootOid#equals(Object) equals} method returns <tt>false</tt>).
087         * 
088         * <p>
089         */
090        NOT_EQUIVALENT,
091    }
092    
093    Comparison compareAgainst(RootOid oid2);
094
095    Bookmark asBookmark();
096
097
098}