001//
002// Name
003//  $RCSfile: KeyManager.java,v $
004// 
005// Copyright
006//  Copyright 2009-2015 Cloud Software Group, Inc. ALL RIGHTS RESERVED.
007//  Cloud Software Group, Inc. Confidential Information
008//
009// History
010//  $Revision: 1.1.2.9 $ $Date: 2015/01/27 03:24:47 $
011//
012package com.kabira.platform;
013
014/**
015 * Factory for KeyQuery instances.  
016 */
017public class KeyManager<T>
018{
019    /**
020     * Creates a KeyManager instance.
021     */
022    public KeyManager() { }
023
024    /**
025     * Returns a new instance of a KeyQuery class.
026     *
027     * @param klass Class containing the key.
028     * @param keyName Name defining the key.
029     * @return KeyQuery instance.
030     * @exception KeyUnknownKeyNameError
031     *  The given keyName is not defined for the type.
032     */
033    public KeyQuery<T> createKeyQuery(
034            final Class<T> klass,
035            final String keyName)
036        throws KeyUnknownKeyNameError
037    {
038        return new KeyQuery<T>(klass, keyName);
039    }
040
041    /**
042     * Returns a new instance of a KeyQuery class.
043     *
044     * @param className Class name containing the key.
045     * @param keyName Name defining the key.
046     * @return KeyQuery instance.
047     * @exception KeyUnknownKeyNameError
048     *  The given keyName is not defined for the type.
049     */
050    public KeyQuery<T> createKeyQuery(
051            final String className,
052            final String keyName)
053        throws KeyUnknownKeyNameError
054    {
055        return new KeyQuery<T>(className, keyName);
056    }
057
058    /**
059     * Update the key indexes for the given object.
060     * <p>
061     * This method must be called after any mutable key fields have been
062     * updated to insure the key indexes reflects the field values. If
063     * the Managed object has no keys, or no key fields have been
064     * modified, this method quietly does nothing.
065     * <p>
066     * If mutable key fields are updated, and this method is not called,
067     * a fatal exception is thrown by the runtime at commit time.
068     * <p>
069     * This method does not need to be executed in a constructor, key
070     * field changes made in constructors are automatically applied to
071     * key indexes when the constructor finishes execution.
072     * 
073     * @param obj Object containing the modified key fields.
074     *
075     * @exception ObjectNotUniqueError
076     *  The updated fields would result in a duplicate instance.
077     * @exception ManagedClassError if object is not Managed.
078     */
079    public static void updateIndexes(final Object obj)
080        throws ObjectNotUniqueError, ManagedClassError
081    {
082        _updateIndexes(ManagedObject.getObjectReference(obj, "updateIndexes"));
083    }
084
085    /**
086     * Access the key data for the given object and key.
087     * <p>
088     * This method returns a byte array containing the key data stored in
089     * the fields that comprise a key for the object. This byte array can be
090     * used to compute a hash value for the instance by key value. 
091     * 
092     * @param obj Object containing the key fields.
093     * @param keyName Name defining the key.
094     *
095     * @return Byte array containing key data.
096     *
097     * @exception ManagedClassError
098     *  The object is not Managed.
099     * @exception KeyUnknownKeyNameError
100     *  The given keyName is not defined for the object class.
101     */
102    public static byte [] getKeyData(final Object obj, final String keyName)
103        throws ManagedClassError, KeyUnknownKeyNameError
104    {
105        return _getKeyData(
106            ManagedObject.getObjectReference(obj, "getKeyData"), keyName);
107    }
108
109    private static native void _updateIndexes(final byte[] objRef);
110    private static native byte [] _getKeyData(
111            final byte[] objRef, final String keyName);
112}