1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package android.hardware.camera2.marshal;
17
18import android.hardware.camera2.utils.TypeReference;
19
20/**
21 * Query if a marshaler can marshal to/from a particular native and managed type; if it supports
22 * the combination, allow creating a marshaler instance to do the serialization.
23 *
24 * <p>Not all queryable instances will support exactly one combination. Some, such as the
25 * primitive queryable will support all primitive to/from managed mappings (as long as they are
26 * 1:1). Others, such as the rectangle queryable will only support integer to rectangle mappings.
27 * </p>
28 *
29 * <p>Yet some others are codependent on other queryables; e.g. array queryables might only support
30 * a type map for {@code T[]} if another queryable exists with support for the component type
31 * {@code T}.</p>
32 */
33public interface MarshalQueryable<T> {
34    /**
35     * Create a marshaler between the selected managed and native type.
36     *
37     * <p>This marshaler instance is only good for that specific type mapping; and will refuse
38     * to map other managed types, other native types, or an other combination that isn't
39     * this exact one.</p>
40     *
41     * @param managedType a managed type reference
42     * @param nativeType the native type, e.g.
43     *          {@link android.hardware.camera2.impl.CameraMetadataNative#TYPE_BYTE TYPE_BYTE}
44     * @return
45     *
46     * @throws UnsupportedOperationException
47     *          if {@link #isTypeMappingSupported} returns {@code false}
48     */
49    public Marshaler<T> createMarshaler(
50            TypeReference<T> managedType, int nativeType);
51
52    /**
53     * Determine whether or not this query marshal is able to create a marshaler that will
54     * support the managed type and native type mapping.
55     *
56     * <p>If this returns {@code true}, then a marshaler can be instantiated by
57     * {@link #createMarshaler} that will marshal data to/from the native type
58     * from/to the managed type.</p>
59     *
60     * <p>Most marshalers are likely to only support one type map.</p>
61     */
62    public boolean isTypeMappingSupported(TypeReference<T> managedType, int nativeType);
63}
64