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, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.mapred.nativetask;
020
021import org.apache.hadoop.classification.InterfaceAudience;
022import org.apache.hadoop.classification.InterfaceStability;
023
024/**
025 * Any key type that is comparable at native side must implement this interface.
026 *
027 * A native comparator function should have the ComparatorPtr type:
028 * <code>
029 *   typedef int (*ComparatorPtr)(const char * src, uint32_t srcLength,
030 *   const char * dest,  uint32_t destLength);
031 * </code>
032 * Keys are in serialized format at native side. The function has passed in
033 * the keys' locations and lengths such that we can compare them in the same
034 * logic as their Java comparator.
035 *
036 * For example, a HiveKey serialized as an int field (containing the length of
037 * raw bytes) + raw bytes.
038 * When comparing two HiveKeys, we first read the length field and then
039 * compare the raw bytes by invoking the BytesComparator provided by our library.
040 * We pass the location and length of raw bytes into BytesComparator.
041 *
042 * <code>
043 *   int HivePlatform::HiveKeyComparator(const char * src, uint32_t srcLength,
044 *   const char * dest, uint32_t destLength) {
045 *     uint32_t sl = bswap(*(uint32_t*)src);
046 *     uint32_t dl = bswap(*(uint32_t*)dest);
047 *     return NativeObjectFactory::BytesComparator(src + 4, sl, dest + 4, dl);
048 *   }
049 * </code>
050 */
051@InterfaceAudience.Public
052@InterfaceStability.Evolving
053public interface INativeComparable {
054}