Juan Hernandez has uploaded a new change for review.
Change subject: restapi: Add "size" attribute support
......................................................................
restapi: Add "size" attribute support
This patch adds support for a new "size" attribute for collections. The
value of this parameter can be one of the following:
include
Indicates that the size attribute should be populated.
exclude
Indicates that the size attribute should't be populated. This will
be the default in order to preserve backwards compatibility.
only
Indicates that only the size attribute should be populated, and
that the actual data shouldn't. This is intended for situations
where the caller wants to know the size of the collection but
doesn't want to transfer a potentially large amount of data
that won't actually be used.
When the size is populated it will look like this (for templates, for
example):
GET /templates;size=include
<templates>
<size>123</size>
<template id="..." href="...">
...
</template>
...
</templates>
When only the size is populated it will look like this:
GET /templates;size=only
<templates>
<size>123</size>
</templates>
This patch also includes support for this parameter in the templates
collection, as an example.
Change-Id: I6f39413ea33319a21fd48018017fce8030ecbf14
Bug-Url: https://bugzilla.redhat.com/1132249
Signed-off-by: Juan Hernandez <[email protected]>
---
A
backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviour.java
A
backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviourHelper.java
M
backend/manager/modules/restapi/interface/definition/src/main/resources/api.xsd
M
backend/manager/modules/restapi/jaxrs/src/main/java/org/ovirt/engine/api/restapi/resource/BackendTemplatesResource.java
4 files changed, 160 insertions(+), 17 deletions(-)
git pull ssh://gerrit.ovirt.org:29418/ovirt-engine refs/changes/23/34223/1
diff --git
a/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviour.java
b/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviour.java
new file mode 100644
index 0000000..1633bab
--- /dev/null
+++
b/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviour.java
@@ -0,0 +1,56 @@
+/*
+* Copyright (c) 2014 Red Hat, Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+package org.ovirt.engine.api.common.util;
+
+/**
+ * This enum represents what should be the behaviour of the RESTAPI when it
receives the {@code size} matrix parameter
+ * in a request to list a collection.
+ */
+public enum SizeBehaviour {
+ /**
+ * Indicates that the size should be included in the result.
+ */
+ INCLUDE,
+
+ /**
+ * Indicates that the size shouldn't be included in the result.
+ */
+ EXCLUDE,
+
+ /**
+ * Indicates that only the size should be included in the result, and that
the actual data shouldn't be included.
+ * This is intended for situations where the caller only wants to count
the number of items, without the overhead
+ * of transferring all their content.
+ */
+ ONLY;
+
+ /**
+ * This methods returns {@code true} iff the value of the enum indicates
that size should be included in the
+ * result.
+ */
+ public boolean includeSize() {
+ return this != EXCLUDE;
+ }
+
+ /**
+ * This methods returns {@code true} iff the value of the enum indicates
that actual data should be included in the
+ * result.
+ */
+ public boolean includeData() {
+ return this != ONLY;
+ }
+}
diff --git
a/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviourHelper.java
b/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviourHelper.java
new file mode 100644
index 0000000..1f1b17a
--- /dev/null
+++
b/backend/manager/modules/restapi/interface/common/jaxrs/src/main/java/org/ovirt/engine/api/common/util/SizeBehaviourHelper.java
@@ -0,0 +1,62 @@
+/*
+* Copyright (c) 2014 Red Hat, Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+package org.ovirt.engine.api.common.util;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.ws.rs.core.MultivaluedMap;
+import javax.ws.rs.core.UriInfo;
+
+/**
+ * A utility class to handle the {@code size} matrix parameter for
collections. This parameter is used to control how the
+ * of the collection should be reported. See the {@link SizeBehaviour} class
for details.
+ */
+public class SizeBehaviourHelper {
+ private static final Logger log =
LoggerFactory.getLogger(SizeBehaviourHelper.class);
+ /**
+ * The name of the parameter.
+ */
+ private static final String PARAMETER_NAME = "size";
+
+ /**
+ * Analyzes the given URI and extracts the value of the {@code size}
parameter. If the parameter isn't included
+ * in the URI, or it has an incorrect value, it will return the default
value {@link SizeBehaviour#EXCLUDE} in order
+ * to preserve backwards compatibility.
+ *
+ * @param uri the URI where the parameter will be extracted from
+ * @return the value of the parameter if given, or {@link
SizeBehaviour#EXCLUDE} if it not given or incorrect, will
+ * never return {@code null}
+ */
+ public static SizeBehaviour getSizeBehaviour(UriInfo uri) {
+ // Extract the value from the matrix parameter:
+ MultivaluedMap<String, String> parameters = uri.getPathParameters();
+ String value = parameters.getFirst(PARAMETER_NAME);
+ if (value != null) {
+ String upper = value.toUpperCase();
+ try {
+ return SizeBehaviour.valueOf(upper);
+ }
+ catch (IllegalArgumentException exception) {
+ log.warn("Unknonwn size behaviour \"" + value + "\" requested,
will use the default", exception);
+ }
+ }
+
+ // The default is to exclude the size, to preserve backwards
compatibility:
+ return SizeBehaviour.EXCLUDE;
+ }
+}
diff --git
a/backend/manager/modules/restapi/interface/definition/src/main/resources/api.xsd
b/backend/manager/modules/restapi/interface/definition/src/main/resources/api.xsd
index 0a2119a..b4c6662 100644
---
a/backend/manager/modules/restapi/interface/definition/src/main/resources/api.xsd
+++
b/backend/manager/modules/restapi/interface/definition/src/main/resources/api.xsd
@@ -1214,7 +1214,17 @@
<xs:complexContent>
<xs:extension base="ActionableResource">
<xs:sequence>
+ <!-- The "size" of the collection is the actual number of items
+ returned as a result. For example, when using the "max"
+ parameter the set of returned items may be different than
+ the total. -->
+ <xs:element name="size" type="xs:unsignedInt" minOccurs="0"/>
+
+ <!-- The "total" is the total number of items that match the
+ restrictions given by the caller, regardless of the value
+ of the "max" parameter. -->
<xs:element name="total" type="xs:unsignedInt" minOccurs="0"/>
+
<xs:element name="active" type="xs:unsignedInt" minOccurs="0"/>
</xs:sequence>
</xs:extension>
diff --git
a/backend/manager/modules/restapi/jaxrs/src/main/java/org/ovirt/engine/api/restapi/resource/BackendTemplatesResource.java
b/backend/manager/modules/restapi/jaxrs/src/main/java/org/ovirt/engine/api/restapi/resource/BackendTemplatesResource.java
index 5067070..95f138e 100644
---
a/backend/manager/modules/restapi/jaxrs/src/main/java/org/ovirt/engine/api/restapi/resource/BackendTemplatesResource.java
+++
b/backend/manager/modules/restapi/jaxrs/src/main/java/org/ovirt/engine/api/restapi/resource/BackendTemplatesResource.java
@@ -7,6 +7,8 @@
import javax.ws.rs.core.Response;
+import org.ovirt.engine.api.common.util.SizeBehaviourHelper;
+import org.ovirt.engine.api.common.util.SizeBehaviour;
import org.ovirt.engine.api.model.Console;
import org.ovirt.engine.api.model.Disk;
import org.ovirt.engine.api.model.Template;
@@ -51,11 +53,15 @@
@Override
public Templates list() {
- if (isFiltered())
- return
mapCollection(getBackendCollection(VdcQueryType.GetAllVmTemplates,
- new VdcQueryParametersBase()));
- else
- return mapCollection(getBackendCollection(SearchType.VmTemplate));
+ List<VmTemplate> entities;
+ if (isFiltered()) {
+ entities = getBackendCollection(VdcQueryType.GetAllVmTemplates,
+ new VdcQueryParametersBase());
+ }
+ else {
+ entities = getBackendCollection(SearchType.VmTemplate);
+ }
+ return mapCollection(entities);
}
@Override
@@ -161,22 +167,31 @@
}
protected Templates mapCollection(List<VmTemplate> entities) {
- // Fill VmInit for entities - the search query no join the VmInit to
Templates
- IdsQueryParameters params = new IdsQueryParameters();
- List<Guid> ids = Entities.getIds(entities);
- params.setId(ids);
- VdcQueryReturnValue queryReturnValue =
runQuery(VdcQueryType.GetVmsInit, params);
- if (queryReturnValue.getSucceeded() &&
queryReturnValue.getReturnValue() != null) {
- List<VmInit> vmInits = queryReturnValue.getReturnValue();
- Map<Guid, VmInit> initMap = Entities.businessEntitiesById(vmInits);
- for (VmTemplate template : entities) {
- template.setVmInit(initMap.get(template.getId()));
+ SizeBehaviour sizeBehaviour =
SizeBehaviourHelper.getSizeBehaviour(getUriInfo());
+
+ if (sizeBehaviour.includeData()) {
+ // Fill VmInit for entities - the search query no join the VmInit
to Templates
+ IdsQueryParameters params = new IdsQueryParameters();
+ List<Guid> ids = Entities.getIds(entities);
+ params.setId(ids);
+ VdcQueryReturnValue queryReturnValue =
runQuery(VdcQueryType.GetVmsInit, params);
+ if (queryReturnValue.getSucceeded() &&
queryReturnValue.getReturnValue() != null) {
+ List<VmInit> vmInits = queryReturnValue.getReturnValue();
+ Map<Guid, VmInit> initMap =
Entities.businessEntitiesById(vmInits);
+ for (VmTemplate template : entities) {
+ template.setVmInit(initMap.get(template.getId()));
+ }
}
}
Templates collection = new Templates();
- for (VmTemplate entity : entities) {
- collection.getTemplates().add(addLinks(populate(map(entity),
entity)));
+ if (sizeBehaviour.includeData()) {
+ for (VmTemplate entity : entities) {
+ collection.getTemplates().add(addLinks(populate(map(entity),
entity)));
+ }
+ }
+ if (sizeBehaviour.includeSize()) {
+ collection.setSize((long) entities.size());
}
return collection;
}
--
To view, visit http://gerrit.ovirt.org/34223
To unsubscribe, visit http://gerrit.ovirt.org/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I6f39413ea33319a21fd48018017fce8030ecbf14
Gerrit-PatchSet: 1
Gerrit-Project: ovirt-engine
Gerrit-Branch: master
Gerrit-Owner: Juan Hernandez <[email protected]>
_______________________________________________
Engine-patches mailing list
[email protected]
http://lists.ovirt.org/mailman/listinfo/engine-patches
