001//
002// Name
003//  $RCSfile: PartitionMapper.java,v $
004// 
005// Copyright
006//  Copyright 2010-2015 Cloud Software Group, Inc. ALL RIGHTS RESERVED. 
007//  Cloud Software Group, Inc. Confidential Information
008//
009// History
010//  $Revision: 1.1.2.10.2.1 $ $Date: 2015/04/30 19:58:03 $
011//
012package com.kabira.platform.highavailability;
013
014import com.kabira.platform.annotation.Managed;
015import com.kabira.platform.disteng.DEPartitionMapper;
016
017//
018// Transaction note:
019//
020// The object instance passed in will be write locked if the instance is
021// being created, or with no lock if the partition is being updated.
022// Since applications will probably read attributes of the object when
023// this is called, partition updates will tend to read lock all
024// instances, unless we support dirty reads. One thing we need to do is
025// insure that the object reference can be accessed with no locking, this
026// will allow oid based partitioning with no object locking involved.
027//
028
029/**
030 * The PartitionMapper class. This managed class is extended by applications
031 * to partition instances. Note that applications should never define fields
032 * in the subclass to avoid any transaction locks.
033 */
034@Managed
035public abstract class PartitionMapper extends DEPartitionMapper
036{
037    /**
038     * The Mapper properties used when defining a partition mapper.
039     */
040    public final static class Properties
041    {
042        /**
043         * An enumeration of the possible audits that can be taken when
044         * setting a PartitionMapper for a given type.
045         */
046        public enum Audit
047        {
048            /**
049             * @deprecated Replaced by {@link Properties.Audit#VERIFY_PARTITIONING}
050             */
051            @Deprecated
052            VERIFY_PARTIONING,
053            /**
054             * Verify that no unpartitioned instances of the given type
055             * exist in shared memory.
056             */
057            VERIFY_PARTITIONING,
058            /**
059             * Verify that no unpartitioned instances of the given type
060             * exist in shared memory. If the type doesn't exist in shared
061             * memory, have the runtime defer installation until the type
062             * is created. 
063             */
064            VERIFY_DEFER_INSTALL,
065            /**
066             * Do not perform any verification of previously created instances.
067             */
068            IGNORE_PARTITIONING,
069        }
070
071        /**
072         * Default constructor. The default audit used is
073         * {@link Audit#IGNORE_PARTITIONING}.
074         */
075        public Properties()
076        {
077            m_audit = Audit.IGNORE_PARTITIONING;
078        }
079
080        /**
081         * Constructor containing audits value.
082         *
083         * @param audit What auditing should be done.
084         *
085         */
086        public Properties(final Audit audit)
087        {
088            m_audit = audit;
089        }
090
091        /**
092         * Set the audit value.
093         *
094         * @param audit What auditing should be done.
095         *
096         */
097        public void setAudit(final Audit audit)
098        {
099            m_audit = audit;
100        }
101
102        /**
103         * Get the audit value.
104         *
105         * @return Currently defined audit value.
106         */
107        public Audit getAudit()
108        {
109            return m_audit;
110        }
111
112        Audit m_audit;
113    }
114
115    /**
116     * String to return from getPartition() if object should not be partitioned
117     */ 
118    public static final String  NOT_PARTITIONED = "__none_";
119
120    //
121    // FIX THIS: issue FLUENCY-3275: This causes a crash in typdsc.cpp
122    //
123    // static final String  NOT_PARTITIONED = 
124    //     com.kabira.platform.disteng.PartitionMapper.NotPartitioned();
125    //
126
127    //
128    // Note: We return a String instead of a Partition instance for
129    // performance, this call is made for every create object, or when
130    // partitions are updated.
131    //
132    /**
133     * Determine which partition a given object is associated with.
134     *
135     * If an invalid partition name is returned from this method, the
136     * runtime will throw a com.kabira.platform.ResourceUnavailableException
137     * exception to the caller creating the instance.
138     *
139     * @param obj   A managed object instance.
140     * @return      The name of a pre-existing partition. 
141     */
142        public abstract String getPartition(Object obj);
143}