1 /*
2 * #%L
3 * prolobjectlink-jpi
4 * %%
5 * Copyright (C) 2019 Prolobjectlink Project
6 * %%
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 * #L%
25 */
26 package io.github.prolobjectlink.prolog;
27
28 import java.util.Map;
29
30 /**
31 * PrologMapper is an special converter that help to do casting operations from
32 * Prolog terms to the equivalent native terms and vice versa. The methods
33 * contained in this interface specify the class for the final resulting object.
34 *
35 * @author Jose Zalacain
36 * @since 1.0
37 */
38 interface PrologMapper {
39
40 /**
41 * Create an equivalent Prolog terms map array using the given native terms map
42 * array representation and cast every Prolog term to some specific given class.
43 * The resulting map array contains map that have the same string key and the
44 * value for every key is a conversion from native term to Prolog term.
45 *
46 * @param map native terms map array to be converted in Prolog terms map array.
47 * @param from class to be cast the result Prolog term
48 * @param <K> generic type that extends from {@link PrologTerm}
49 * @param <V> generic type that extends from {@link Object} representing a
50 * native prolog term.
51 * @return an equivalent Prolog terms map array using the given native terms map
52 * array representation of given class type.
53 * @since 1.0
54 */
55 <K extends PrologTerm, V extends Object> Map<String, PrologTerm>[] toTermMapArray(Map<String, V>[] map,
56 Class<K> from);
57
58 /**
59 * Create an equivalent Prolog terms map using the given native terms map
60 * representation and cast every Prolog term to some specific given class. The
61 * resulting map have the same string key and the value for every key is a
62 * conversion from native term to Prolog term.
63 *
64 * @param map native terms map representation to be converted
65 * @param from class to be cast the result Prolog term
66 * @param <K> generic type that extends from {@link PrologTerm}
67 * @param <V> generic type that extends from {@link Object} representing a
68 * native prolog term.
69 * @return an equivalent Prolog terms map using the given native terms map
70 * representation of given class type.
71 * @since 1.0
72 */
73 <K extends PrologTerm, V extends Object> Map<String, PrologTerm> toTermMap(Map<String, V> map, Class<K> from);
74
75 /**
76 * Create an equivalent Prolog terms matrix using the given native terms matrix
77 * representation and cast every Prolog terms matrix to some specific matrix
78 * component class.
79 *
80 * @param objects native terms matrix representation to be converted
81 * @param from class to be cast the result Prolog term
82 * @param <K> generic type that extends from {@link PrologTerm}
83 * @return an equivalent Prolog terms matrix using the given native terms matrix
84 * representation of array component class type.
85 * @since 1.0
86 */
87 <K extends PrologTerm> K[][] toTermMatrix(Object[][] objects, Class<K[][]> from);
88
89 /**
90 * Create an equivalent Prolog terms array using the given native terms array
91 * representation and cast this Prolog term array to some specific array
92 * component class.
93 *
94 * @param objects native terms array representation to be converted
95 * @param from class to be cast the result Prolog term
96 * @param <K> generic type that extends from {@link PrologTerm}
97 * @return an equivalent Prolog terms array using the given native terms array
98 * representation of array component class type.
99 * @since 1.0
100 */
101 <K extends PrologTerm> K[] toTermArray(Object[] objects, Class<K[]> from);
102
103 /**
104 * Create an equivalent Prolog term using the given native term representation
105 * and cast this Prolog term to some specific given class.
106 *
107 * @param o native term representation to be converted
108 * @param from class to be cast the result Prolog term
109 * @param <K> generic type that extends from {@link PrologTerm}
110 * @return an equivalent Prolog term using the given native term representation
111 * of given class type.
112 * @since 1.0
113 */
114 <K extends PrologTerm> K toTerm(Object o, Class<K> from);
115
116 /**
117 * Create a native rule representation term from given head and body and cast
118 * this native term to some specific given class.
119 *
120 * @param term Prolog term to be converted to native term.
121 * @param to class to be cast the result native term
122 * @param <K> generic type that represent native prolog type
123 * @return rule representation from given head and body of given class type.
124 * @since 1.0
125 */
126 <K> K fromTerm(PrologTerm term, Class<K> to);
127
128 /**
129 * Create a native term array representation from given Prolog term array and
130 * cast this native term array to some specific given array class.
131 *
132 * @param terms Prolog term array to be converted to native array.
133 * @param to class to be cast the result native term
134 * @param <K> generic type that represent native prolog type
135 * @return native term array representation from given Prolog term array of
136 * given array class type.
137 * @since 1.0
138 */
139 <K> K[] fromTermArray(PrologTerm[] terms, Class<K[]> to);
140
141 /**
142 * Create a native rule representation term from given head and body and cast
143 * this native term to some specific given class.
144 *
145 * @param head rule head
146 * @param body rule body
147 * @param to class to be cast the result native term
148 * @param <K> generic type that represent native prolog type
149 * @return rule representation from given head and body of given class type.
150 * @since 1.0
151 */
152 <K> K fromTerm(PrologTerm head, PrologTerm[] body, Class<K> to);
153
154 }