Changeset 6917

Timestamp:

01/18/16 16:40:03 (8 years ago)

Author:

Oliver Schonefeld

Message:

• enhance endpoint description parser

Location:

SRUClient/trunk/src

Files:

• main/java/eu/clarin/sru/client/fcs/ClarinFCSEndpointDescription.java (modified) (10 diffs)
• main/java/eu/clarin/sru/client/fcs/ClarinFCSEndpointDescriptionParser.java (modified) (12 diffs)
• test/java/eu/clarin/sru/client/TestUtils.java (modified) (2 diffs)

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/ClarinFCSEndpointDescription.java

@@ -21 +21 @@
     private final List<URI> capabilites;
     private final List<DataView> supportedDataViews;
+    private final List<Layer> supportedLayers;
     private final List<ResourceInfo> resources;
 
 
     ClarinFCSEndpointDescription(int version, List<URI> capabilites,
-            List<DataView> supportedDataViews, List<ResourceInfo> resources) {
+            List<DataView> supportedDataViews, List<Layer> supportedLayers,
+            List<ResourceInfo> resources) {
         this.version = version;
         if ((capabilites != null) && !capabilites.isEmpty()) {
@@ -38 +40 @@
             this.supportedDataViews = Collections.emptyList();
         }
+        if ((supportedLayers != null) && !supportedLayers.isEmpty()) {
+            this.supportedLayers =
+                    Collections.unmodifiableList(supportedLayers);
+        } else {
+            this.supportedLayers = Collections.emptyList();
+        }
         if ((resources != null) && !resources.isEmpty()) {
             this.resources = Collections.unmodifiableList(resources);
@@ -85 +93 @@
 
     /**
+     * Get the list of data views supported by this endpoint.
+     *
+     * @return the list of data views supported by this endpoint
+     */
+    public List<Layer> getSupportedLayers() {
+        return supportedLayers;
+    }
+
+
+    /**
      * Get the list of top-level resources of this endpoint.
      *
@@ -98 +116 @@
      */
     public static final class DataView implements Serializable {
-        private static final long serialVersionUID = -5628565233032672627L;
-
-
         /**
          * Enumeration to indicate the delivery policy of a data view.
@@ -114 +129 @@
             NEED_TO_REQUEST;
         } // enum PayloadDelivery
+        private static final long serialVersionUID = -5628565233032672627L;
         private final String identifier;
         private final String mimeType;
@@ -188 +204 @@
             return sb.toString();
         }
-
     } // class DataView
+
+
+    public static final class Layer implements Serializable {
+        /**
+         * Enumeration to indicate the content encoding of a layer.
+         */
+        public enum ContentEncoding {
+            /**
+             * The layer is encoded as content values.
+             */
+            VALUE,
+            /**
+             * The layer is encoded just as segment units.
+             */
+            EMPTY
+        }
+        private static final long serialVersionUID = 6641490182609459912L;
+        private final String identifier;
+        private final URI resultId;
+        private final String layerType;
+        private final ContentEncoding encoding;
+        private final String qualifier;
+        private final String altValueInfo;
+        private final URI altValueInfoURI;
+
+
+        public Layer(String identifier, URI resultId, String layerType,
+                ContentEncoding encoding, String qualifier,
+                String altValueInfo, URI altValueInfoURI) {
+            if (identifier == null) {
+                throw new NullPointerException("identifier == null");
+            }
+            if (identifier.isEmpty()) {
+                throw new IllegalArgumentException("identifier is empty");
+            }
+            this.identifier = identifier;
+
+            if (resultId == null) {
+                throw new NullPointerException("resultId == null");
+            }
+            this.resultId = resultId;
+
+            if (layerType == null) {
+                throw new NullPointerException("layerType == null");
+            }
+            if (layerType.isEmpty()) {
+                throw new IllegalArgumentException("layerType is empty");
+            }
+            this.layerType = layerType;
+            this.encoding = (encoding != null)
+                    ? encoding
+                    : ContentEncoding.VALUE;
+            this.qualifier = qualifier;
+            this.altValueInfo = altValueInfo;
+            this.altValueInfoURI = altValueInfoURI;
+        }
+
+
+        /**
+         * Get the identifier of this layer
+         *
+         * @return the identifier of the layer
+         */
+        public String getIdentifier() {
+            return identifier;
+        }
+
+
+        /**
+         * Get the result URI of this layer
+         *
+         * @return the result URI of the layer
+         */
+        public URI getResultId() {
+            return resultId;
+        }
+
+
+        /**
+         * Get the layer type of this layer
+         *
+         * @return the layer type of the layer
+         */
+        public String getLayerType() {
+            return layerType;
+        }
+
+
+        /**
+         * Get the content encoding of this layer
+         *
+         * @return the content encoding of the layer
+         */
+        public ContentEncoding getEncoding() {
+            return encoding;
+        }
+
+
+        /**
+         * Get the qualifier of this layer
+         *
+         * @return the qualifier of the layer or <code>null</code> if none
+         */
+        public String getQualifier() {
+            return qualifier;
+        }
+
+
+        /**
+         * Get the alternative value information of this layer
+         *
+         * @return the alternative value information of the layer or
+         *         <code>null</code> if none
+         */
+        public String getAltValueInfo() {
+            return altValueInfo;
+        }
+
+
+        /**
+         * Get the alternative value information URI of this layer
+         *
+         * @return the alternative value information URI of the layer or
+         *         <code>null</code> if none
+         */
+        public URI getAltValueInfoURI() {
+            return altValueInfoURI;
+        }
+
+
+        @Override
+        public String toString() {
+            StringBuilder sb = new StringBuilder();
+            sb.append(getClass().getSimpleName());
+            sb.append("[");
+            sb.append("identifier=").append(identifier);
+            sb.append(", result-id=").append(resultId);
+            sb.append(", layer-type=").append(layerType);
+            if (encoding != null) {
+                sb.append(", encoding=").append(encoding);
+            }
+            if (qualifier != null) {
+                sb.append(", qualifier=").append(qualifier);
+            }
+            if (altValueInfo != null) {
+                sb.append(", alt-value-info=").append(altValueInfo);
+            }
+            if (altValueInfoURI != null) {
+                sb.append(", alt-value-info-uri=").append(altValueInfoURI);
+            }
+            sb.append("]");
+            return sb.toString();
+        }
+    }
 
 
@@ -204 +373 @@
         private final List<String> languages;
         private final List<DataView> availableDataViews;
+        private final List<Layer> availableLayers;
         private final List<ResourceInfo> subResources;
 
@@ -213 +383 @@
                 Map<String, String> description, String landingPageURI,
                 List<String> languages, List<DataView> availableDataViews,
+                List<Layer> availableLayers,
                 List<ResourceInfo> subResources) {
             if (pid == null) {
@@ -247 +418 @@
                     Collections.unmodifiableList(availableDataViews);
 
+            if ((availableLayers != null) && !availableLayers.isEmpty()) {
+                this.availableLayers =
+                        Collections.unmodifiableList(availableLayers);
+            } else {
+                this.availableLayers = Collections.emptyList();
+            }
+
             if ((subResources != null) && !subResources.isEmpty()) {
                 this.subResources = Collections.unmodifiableList(subResources);
@@ -378 +556 @@
 
 
+        /**
+         * Get the list of data views that are available for this resource.
+         *
+         * @return the list of data views available for this resource
+         */
         public List<DataView> getAvailableDataViews() {
             return availableDataViews;
         }
 
+
+        /**
+         * (ADV-FCS) Get the list of layers that are available for this
+         * resource.
+         *
+         * @return the list of layers views available for this resource
+         */
+        public List<Layer> getAvailableLayers() {
+            return availableLayers;
+        }
     } // class ResourceInfo
 

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/ClarinFCSEndpointDescriptionParser.java

@@ -38 +38 @@
 import eu.clarin.sru.client.fcs.ClarinFCSEndpointDescription.DataView;
 import eu.clarin.sru.client.fcs.ClarinFCSEndpointDescription.DataView.DeliveryPolicy;
+import eu.clarin.sru.client.fcs.ClarinFCSEndpointDescription.Layer;
+import eu.clarin.sru.client.fcs.ClarinFCSEndpointDescription.Layer.ContentEncoding;
 import eu.clarin.sru.client.fcs.ClarinFCSEndpointDescription.ResourceInfo;
 
@@ -60 +62 @@
     private static final QName ED_ROOT_ELEMENT =
             new QName(ED_NS_URI, "EndpointDescription");
-    private static final int EXPECTED_VERSION = 1;
+    private static final int VERSION_1 = 1;
+    private static final int VERSION_2 = 2;
     private static final String CAPABILITY_PREFIX =
             "http://clarin.eu/fcs/capability/";
     private static final URI CAPABILITY_BASIC_SEARCH =
             URI.create("http://clarin.eu/fcs/capability/basic-search");
+    private static final URI CAPABILITY_ADVANCED_SEARCH =
+            URI.create("http://clarin.eu/fcs/capability/advanced-search");
     private static final String MIMETYPE_HITS_DATAVIEW =
             "application/x-clarin-fcs-hits+xml";
@@ -105 +110 @@
             throws XMLStreamException, SRUClientException {
         final int version = parseVersion(reader);
-        // FIXME: actually handle other version
-        if ((version != EXPECTED_VERSION) && (version != 2)) {
+        if ((version != VERSION_1) && (version != VERSION_2)) {
             throw new SRUClientException("Attribute 'version' of " +
-                    "element '<EndpointDescription>' must be of value '1'");
-        }
-        logger.error("VERSION: {}", version);
+                    "element '<EndpointDescription>' must be of value '1' or '2'");
+        }
         reader.next(); // consume start tag
 
@@ -139 +142 @@
         } // while
         XmlStreamReaderUtils.readEnd(reader, ED_NS_URI, "Capabilities");
-        if ((capabilities == null) ||
-                (capabilities.indexOf(CAPABILITY_BASIC_SEARCH) == -1)) {
+
+        if (capabilities == null) {
+            throw new SRUClientException("Endpoint must support at " +
+                    "least one capability!");
+        }
+        final boolean hasBasicSearch =
+                (capabilities.indexOf(CAPABILITY_BASIC_SEARCH) != -1);
+        final boolean hasAdvancedSearch =
+                (capabilities.indexOf(CAPABILITY_ADVANCED_SEARCH) != -1);
+        if (!hasBasicSearch) {
             throw new SRUClientException("Endpoint must support " +
                     "'basic-search' (" + CAPABILITY_BASIC_SEARCH +
@@ -205 +216 @@
 
         // SupportedLayers
-        // FIXME: actually do something useful
+        List<Layer> supportedLayers = null;
         if (XmlStreamReaderUtils.readStart(reader, ED_NS_URI,
                 "SupportedLayers", false)) {
+            while (XmlStreamReaderUtils.readStart(reader, ED_NS_URI,
+                    "SupportedLayer", (supportedLayers == null), true)) {
+                final String id = XmlStreamReaderUtils.readAttributeValue(reader, null, "id");
+                if ((id.indexOf(' ') != -1) || (id.indexOf(',') != -1) ||
+                        (id.indexOf(';') != -1)) {
+                    throw new XMLStreamException("Value of attribute 'id' on " +
+                            "element '<SupportedLayer>' may not contain the " +
+                            "characters ',' (comma) or ';' (semicolon) " +
+                            "or ' ' (space)", reader.getLocation());
+                }
+                URI resultId = null;
+                final String s1 =
+                        XmlStreamReaderUtils.readAttributeValue(reader,
+                                null, "result-id");
+                try {
+                    resultId = new URI(s1);
+                } catch (URISyntaxException e) {
+                    throw new XMLStreamException("'result-id' must be encoded " +
+                            "as URIs (offending value = '" + s1 + "')",
+                            reader.getLocation(), e);
+                }
+                final ContentEncoding encoding = parseContentEncoding(reader);
+                String qualifier = XmlStreamReaderUtils.readAttributeValue(reader, null, "qualifier", false);
+                String altValueInfo = XmlStreamReaderUtils.readAttributeValue(reader, null, "alt-value-info", false);
+                URI altValueInfoURI = null;
+                final String s2 =
+                        XmlStreamReaderUtils.readAttributeValue(reader, null,
+                                "alt-value-info-uri", false);
+                if (s2 != null) {
+                    try {
+                        altValueInfoURI = new URI(s2);
+                    } catch (URISyntaxException e) {
+                        throw new XMLStreamException("'alt-value-info-uri' must be encoded " +
+                                "as URIs (offending value = '" + s2 + "')",
+                                reader.getLocation(), e);
+                    }
+                }
+                reader.next(); // consume element
+                final String layer = XmlStreamReaderUtils.readString(reader, true);
+                logger.debug("layer: id={}, resultId={}, layer={}, encoding={}, qualifier={}, alt-value-info={}, alt-value-info-uri={}",
+                        id, resultId, layer, encoding, qualifier, altValueInfo, altValueInfoURI);
+
+                XmlStreamReaderUtils.readEnd(reader, ED_NS_URI, "SupportedLayer");
+                if (supportedLayers == null) {
+                    supportedLayers = new ArrayList<Layer>();
+                }
+                supportedLayers.add(new Layer(id, resultId, layer,
+                        encoding, qualifier, altValueInfo,
+                        altValueInfoURI));
+            } // while
             XmlStreamReaderUtils.readEnd(reader, ED_NS_URI,
                     "SupportedLayers", true);
         }
+        if (hasAdvancedSearch && (supportedLayers == null)) {
+            throw new SRUClientException("Endpoint must declare " +
+                    "all supported layers (<SupportedLayers>) if they " +
+                    "provide the 'advanced-search' (" +
+                    CAPABILITY_ADVANCED_SEARCH + ") capability");
+        }
+        if (!hasAdvancedSearch && (supportedLayers != null)) {
+            // XXX: hard error?!
+            logger.warn("Endpoint superflously declared supported " +
+                    "layers (<SupportedLayers> without providing the " +
+                    "'advanced-search' (" + CAPABILITY_ADVANCED_SEARCH + ") capability");
+        }
 
         // Resources
         final List<ResourceInfo> resources =
-                parseResources(reader, 0, maxDepth, supportedDataViews);
+                parseResources(reader, 0, maxDepth,
+                        supportedDataViews, supportedLayers);
 
         // skip over extensions
@@ -231 +305 @@
 
         return new ClarinFCSEndpointDescription(version, capabilities,
-                supportedDataViews, resources);
+                supportedDataViews, supportedLayers, resources);
     }
 
@@ -248 +322 @@
 
     private static List<ResourceInfo> parseResources(XMLStreamReader reader,
-            int depth, int maxDepth, List<DataView> supportedDataviews)
-            throws XMLStreamException {
+            int depth, int maxDepth, List<DataView> supportedDataviews,
+            List<Layer> supportedLayers) throws XMLStreamException {
         List<ResourceInfo> resources = null;
 
@@ -298 +372 @@
             logger.debug("languages: {}", languages);
 
+            // AvailableDataViews
             XmlStreamReaderUtils.readStart(reader, ED_NS_URI, "AvailableDataViews", true, true);
             final String dvs = XmlStreamReaderUtils.readAttributeValue(reader, null, "ref", true);
             reader.next(); // consume start tag
             XmlStreamReaderUtils.readEnd(reader, ED_NS_URI, "AvailableDataViews");
-
             List<DataView> dataviews = null;
             for (String dv : dvs.split("\\s+")) {
@@ -324 +398 @@
             logger.debug("DataViews: {}", dataviews);
 
-
-            // FIXME: actually do something useful
-            if (XmlStreamReaderUtils.readStart(reader, ED_NS_URI, "AvailableLayers", false, true)) {
-                final String ls = XmlStreamReaderUtils.readAttributeValue(reader, null, "ref", true);
+            // AvailableLayers
+            List<Layer> layers = null;
+            if (XmlStreamReaderUtils.readStart(reader, ED_NS_URI,
+                    "AvailableLayers", false, true)) {
+                final String ls =
+                        XmlStreamReaderUtils.readAttributeValue(reader,
+                                null, "ref", true);
                 reader.next(); // consume start tag
                 XmlStreamReaderUtils.readEnd(reader, ED_NS_URI, "AvailableLayers");
-                logger.debug("Layers: {}", dataviews);
+                for (String l : ls.split("\\s+")) {
+                    boolean found = false;
+                    for (Layer layer : supportedLayers) {
+                        if (layer.getIdentifier().equals(l)) {
+                            found = true;
+                            if (layers == null) {
+                                layers = new ArrayList<Layer>();
+                            }
+                            layers.add(layer);
+                            break;
+                        }
+                    } // for
+                    if (!found) {
+                        throw new XMLStreamException("Layer with id '" + l +
+                                "' was not declared in <SupportedLayers>",
+                                reader.getLocation());
+                    }
+                } // for
+                logger.debug("Layers: {}", layers);
             }
 
@@ -341 +436 @@
                         (nextDepth < maxDepth)) {
                     subResources = parseResources(reader, nextDepth,
-                            maxDepth, supportedDataviews);
+                            maxDepth, supportedDataviews, supportedLayers);
                 } else {
                     XmlStreamReaderUtils.skipTag(reader, ED_NS_URI,
@@ -366 +461 @@
             }
             resources.add(new ResourceInfo(pid, title, description,
-                    landingPageURI, languages, dataviews, subResources));
+                    landingPageURI, languages, dataviews, layers,
+                    subResources));
         } // while
         XmlStreamReaderUtils.readEnd(reader, ED_NS_URI, "Resources");
@@ -427 +523 @@
     }
 
+
+    private static ContentEncoding parseContentEncoding(XMLStreamReader reader)
+            throws XMLStreamException {
+        final String s = XmlStreamReaderUtils.readAttributeValue(reader,
+                null, "encoding", false);
+        if (s != null) {
+            if ("value".equals(s)) {
+                return ContentEncoding.VALUE;
+            } else if ("need-to-request".equals(s)) {
+                return ContentEncoding.EMPTY;
+            } else {
+                throw new XMLStreamException("Unexpected value '" + s +
+                                "' for attribute 'encoding' on " +
+                                "element '<SupportedLayer>'",
+                        reader.getLocation());
+            }
+        } else {
+            return null;
+        }
+    }
+
 } // class ClarinFCSEndpointDescriptionParser

SRUClient/trunk/src/test/java/eu/clarin/sru/client/TestUtils.java

@@ -239 +239 @@
                     dataView.getDeliveryPolicy());
         } // for
+        for (ClarinFCSEndpointDescription.Layer layer :
+            ed.getSupportedLayers()) {
+            logger.info("  supportedLayer: id={}, result-id={}, " +
+                    "layer-type={}, encoding={}, qualifier={}, " +
+                    "alt-value-info={}, alt-value-info-uri={}",
+                    layer.getIdentifier(),
+                    layer.getResultId(),
+                    layer.getLayerType(),
+                    layer.getEncoding(),
+                    layer.getQualifier(),
+                    layer.getAltValueInfo(),
+                    layer.getAltValueInfoURI());
+        }
         dumpResourceInfo(ed.getResources(), 1, "  ");
     }
@@ -261 +274 @@
                 logger.info("{}    available dataviews: type={}, policy={}",
                         indent, dv.getMimeType(), dv.getDeliveryPolicy());
+            }
+            for (ClarinFCSEndpointDescription.Layer l :
+                ri.getAvailableLayers()) {
+                logger.info("{}    available layers: result-id={}, layer-type={}",
+                        indent, l.getResultId(), l.getLayerType());
             }
             if (ri.hasSubResources()) {