1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21 package org.opencastproject.assetmanager.api.query;
22
23 import org.opencastproject.assetmanager.api.Availability;
24 import org.opencastproject.assetmanager.api.PropertyName;
25 import org.opencastproject.assetmanager.api.Value.ValueType;
26
27 import java.util.Date;
28
29 /**
30 * To phrase queries to the {@link org.opencastproject.assetmanager.api.AssetManager}.
31 * <p>
32 * Implementations are supposed to be immutable so that one builder can be safely
33 * used in a concurrent environment.
34 */
35 public interface AQueryBuilder {
36 /**
37 * Determine what should be included in the result records, i.e. what will actually be fetched from the database.
38 * If no target is given, only the media package ID ({@link ARecord#getMediaPackageId()}) is fetched.
39 * <p>
40 * Use targets to reduce the amount of database IO, e.g. if you're not interested in the attached properties do
41 * not select them. Or, on the other hand if you want to work with properties only, do not select the snapshot
42 * ({@link AQueryBuilder#snapshot()}).
43 * <p>
44 * Please note that a result record always represents a snapshot accompanied by the properties of the whole episode.
45 * That means that always snapshots are being selected. In case a property target is given, it only means that those
46 * properties are added to the result set.
47 * Please also note that properties are stored per episode, not per snapshot.
48 *
49 * @see ARecord
50 */
51 ASelectQuery select(Target... target);
52
53 /**
54 * Create a new deletion query.
55 * <p>
56 * The query will only affect snapshots owned by the given owner. If the target is a property
57 * the owner parameter will be ignored since properties belong to the whole episode and not
58 * to individual snapshots.
59 *
60 * @param owner
61 * the name of the owner or the empty string
62 */
63 ADeleteQuery delete(String owner, Target target);
64
65 //
66 // direct predicate constructors
67 //
68
69 /* -- */
70 Predicate mediaPackageIds(String... mpIds);
71
72 /** Create a predicate to match an snapshot's media package ID. */
73 Predicate mediaPackageId(String mpId);
74
75 /** Get the snapshot's "mediaPackageId" field. Use it to create a predicate. */
76 Field<String> mediapackageId();
77
78 /** Get the snapshot's "seriesId" field. Use it to create a predicate. */
79 Field<String> seriesId();
80
81 /**
82 * Create a predicate to match a snapshot's organization ID.
83 *
84 * @deprecated use {@link #organizationId()}.eq(orgId) instead
85 */
86 Predicate organizationId(String orgId);
87
88 /** Get the snapshot's "organizationId" field. Use it to create a predicate. */
89 Field<String> organizationId();
90
91 /** Get the snapshot's "owner" field. Use it to create a predicate. */
92 Field<String> owner();
93
94 Predicate availability(Availability availability);
95
96 Predicate storage(String storage);
97
98 /** Create a predicate that matches all snapshots with properties of the given namespace. */
99 Predicate hasPropertiesOf(String namespace);
100
101 /** Create a predicate that matches all snapshots with properties. */
102 Predicate hasProperties();
103
104 //
105 // field definitions
106 //
107
108 /** Get the snapshot's "archived" field. Use it to create a predicate. */
109 Field<Date> archived();
110
111 /** Get the snapshot's "version" field. Use it to create a predicate. */
112 VersionField version();
113
114 /**
115 * Create a field to query properties. Each parameter may be wild carded with the empty string.
116 *
117 * @param namespace
118 * the namespace or "" to select all namespaces
119 * @param name
120 * the property name or "" to select all property names
121 */
122 <A> PropertyField<A> property(ValueType<A> ev, String namespace, String name);
123
124 <A> PropertyField<A> property(ValueType<A> ev, PropertyName fqn);
125
126 //
127 // targets of a select or delete query
128 //
129
130 /** Select or delete a snapshot. */
131 Target snapshot();
132
133 /**
134 * Select or delete all properties that belong to the given namespaces.
135 * Use an empty list of arguments to handle all properties of the media package.
136 */
137 Target propertiesOf(String... namespace);
138
139 /**
140 * Select or delete all given properties.
141 * Use an empty list of arguments to handle all properties of the media package.
142 */
143 Target properties(PropertyName... fqn);
144
145 //
146 // zero/neutral elements
147 //
148
149 /**
150 * The zero element of {@link Target}. Selecting nothing just selects nothing.
151 */
152 Target nothing();
153
154 /**
155 * The zero element of {@link Predicate}.
156 * An empty predicate does nothing.
157 */
158 Predicate always();
159 }