001//
002// Name
003//  $RCSfile: PartitionMapper.java,v $
004// 
005// Copyright
006//  Copyright 2010-2012 Cloud Software Group, Inc. ALL RIGHTS RESERVED. 
007//  Cloud Software Group, Inc. Confidential Information
008//
009// History
010//  $Revision: 1.1.2.7 $ $Date: 2012/04/25 21:01:56 $
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             * Verify that no unpartitioned instances of the given type
050             * exist in shared memory.
051             */
052            VERIFY_PARTIONING,
053            /**
054             * Do not perform any verification of previously created instances.
055             */
056            IGNORE_PARTITIONING,
057        }
058
059        /**
060         * Default constructor. The default audit used is
061         * {@link Audit#IGNORE_PARTITIONING}.
062         */
063        public Properties()
064        {
065            m_audit = Audit.IGNORE_PARTITIONING;
066        }
067
068        /**
069         * Constructor containing audits value.
070         *
071         * @param audit What auditing should be done.
072         *
073         */
074        public Properties(final Audit audit)
075        {
076            m_audit = audit;
077        }
078
079        /**
080         * Set the audit value.
081         *
082         * @param audit What auditing should be done.
083         *
084         */
085        public void setAudit(final Audit audit)
086        {
087            m_audit = audit;
088        }
089
090        /**
091         * Get the audit value.
092         *
093         * @return Currently defined audit value.
094         */
095        public Audit getAudit()
096        {
097            return m_audit;
098        }
099
100        Audit m_audit;
101    }
102
103    /*
104     * String to return from getPartition() if object should not be partitioned
105     */ 
106    static final String  NOT_PARTITIONED = "__none_";
107    //
108    // FIX THIS: issue FLUENCY-3275: This causes a crash in typdsc.cpp
109    //
110    // static final String  NOT_PARTITIONED = 
111    //     com.kabira.platform.disteng.PartitionMapper.NotPartitioned();
112    //
113
114    //
115    // Note: We return a String instead of a Partition instance for
116    // performance, this call is made for every create object, or when
117    // partitions are updated.
118    //
119    /**
120     * Determine which partition a given object is associated with.
121     *
122     * If an invalid partition name is returned from this method, the
123     * runtime will throw a com.kabira.platform.ResourceUnavailableException
124     * exception to the caller creating the instance.
125     *
126     * @param obj   A managed object instance.
127     * @return      The name of a pre-existing partition. 
128     */
129        public abstract String getPartition(Object obj);
130}