Author: suat
Date: Fri Apr 13 07:29:53 2012
New Revision: 1325635
URL: http://svn.apache.org/viewvc?rev=1325635&view=rev
Log:
STANBOL-584: Initial Facet,Constraint,ConstrainedDocumentSet interfaces and
their implementations
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstrainedDocumentSetImpl.java
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstraintImpl.java
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/FacetImpl.java
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/ConstrainedDocumentSet.java
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Constraint.java
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Facet.java
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstrainedDocumentSetImpl.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstrainedDocumentSetImpl.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstrainedDocumentSetImpl.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstrainedDocumentSetImpl.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,57 @@
+package org.apache.stanbol.contenthub.search.featured;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.clerezza.rdf.core.UriRef;
+import org.apache.stanbol.contenthub.servicesapi.search.SearchException;
+import
org.apache.stanbol.contenthub.servicesapi.search.featured.ConstrainedDocumentSet;
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Constraint;
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Facet;
+import
org.apache.stanbol.contenthub.servicesapi.search.featured.FeaturedSearch;
+
+public class ConstrainedDocumentSetImpl implements ConstrainedDocumentSet {
+
+ private String queryTerm;
+ private FeaturedSearch featuredSearch;
+ private Set<Constraint> constraints;
+ private Set<Facet> facets;
+
+ public ConstrainedDocumentSetImpl(String queryTerm, FeaturedSearch
featuredSearch) throws SearchException {
+ this.queryTerm = queryTerm;
+ this.featuredSearch = featuredSearch;
+ this.facets = new HashSet<Facet>();
+ this.constraints = new HashSet<Constraint>();
+ }
+
+ @Override
+ public List<UriRef> getDocuments() throws SearchException {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public Set<Constraint> getConstraints() {
+ return this.constraints;
+ }
+
+ @Override
+ public Set<Facet> getFacets() {
+ return this.facets;
+ }
+
+ @Override
+ public ConstrainedDocumentSet narrow(Constraint constraint) throws
SearchException {
+ Set<Constraint> newConstraints = new
HashSet<Constraint>(getConstraints());
+ newConstraints.add(constraint);
+ return featuredSearch.search(queryTerm, newConstraints);
+ }
+
+ @Override
+ public ConstrainedDocumentSet broaden(Constraint constraint) throws
SearchException {
+ Set<Constraint> newConstraints = new
HashSet<Constraint>(getConstraints());
+ newConstraints.remove(constraint);
+ return featuredSearch.search(queryTerm, newConstraints);
+ }
+}
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstraintImpl.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstraintImpl.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstraintImpl.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/ConstraintImpl.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,54 @@
+package org.apache.stanbol.contenthub.search.featured;
+
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Constraint;
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Facet;
+
+public class ConstraintImpl implements Constraint {
+
+ private String value;
+ private Facet facet;
+
+ public ConstraintImpl(String value, Facet facet) {
+ if (value == null || value.equals("")) {
+ throw new IllegalArgumentException("A non-empty value must be
specified");
+ }
+ if (facet == null) {
+ throw new IllegalArgumentException("A non-null facet must be
specified");
+ }
+ this.value = value;
+ this.facet = facet;
+ }
+
+ @Override
+ public Facet getFacet() {
+ return this.facet;
+ }
+
+ @Override
+ public String getValue() {
+ return this.value;
+ }
+
+ @Override
+ public int hashCode() {
+ return value.hashCode() + facet.getLabel(null).hashCode();
+ }
+
+ /**
+ * If the value of two {@link Constraint}s and default labels of their
associated facets are equal,
+ * constraints are treated as equal.
+ */
+ @Override
+ public boolean equals(Object obj) {
+ if (obj instanceof Constraint) {
+ Constraint c = (Constraint) obj;
+ if (c.getValue().equals(this.getValue()) &&
c.getFacet().equals(this.getFacet())) {
+ return true;
+ } else {
+ return false;
+ }
+ } else {
+ return false;
+ }
+ }
+}
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/FacetImpl.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/FacetImpl.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/FacetImpl.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/search/featured/src/main/java/org/apache/stanbol/contenthub/search/featured/FacetImpl.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2012 The Apache Software Foundation.
+ *
+ * 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.apache.stanbol.contenthub.search.featured;
+
+import java.util.List;
+import java.util.Locale;
+import java.util.Set;
+
+import org.apache.clerezza.rdf.core.PlainLiteral;
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Constraint;
+import org.apache.stanbol.contenthub.servicesapi.search.featured.Facet;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class FacetImpl implements Facet {
+ private static final Logger log = LoggerFactory.getLogger(FacetImpl.class);
+
+ private Set<Constraint> constraints;
+
+ private List<PlainLiteral> labels;
+
+ /**
+ * Creates a {@link Facet} with given <code>constraints</code> and
<code>labels</code>. The first item of
+ * label list is considered as the default label of the this facet. The
default label of a facet is
+ * obtained by <code>getLabel(null)</code>.It is important, because any
facets are considered as equal if
+ * their default labels are the same.
+ *
+ * @param constraints
+ * all possible {@link Constraint} corresponding to the facet
values
+ * @param labels
+ * a list of labels representing this facet. First of the
labels passed in this list is
+ * considered as the default value of this facet
+ */
+ public FacetImpl(List<PlainLiteral> labels) {
+ if (labels == null || labels.isEmpty()) {
+ throw new IllegalArgumentException("Label list must include at
least one item");
+ }
+ this.labels = labels;
+ }
+
+ public void setConstraints(Set<Constraint> constraints) {
+ this.constraints = constraints;
+ }
+
+ @Override
+ public Set<Constraint> getConstraints() {
+ return this.constraints;
+ }
+
+ @Override
+ public String getLabel(Locale locale) {
+ if (locale == null) {
+ return labels.get(0).getLexicalForm();
+ } else {
+ for (PlainLiteral pl : labels) {
+ if (pl.getLanguage().toString().equals(locale.getLanguage())) {
+ return pl.getLexicalForm();
+ }
+ }
+ log.warn("There is no label for specified language: {}. Returnin
default label ",
+ locale.getLanguage());
+ return labels.get(0).getLexicalForm();
+ }
+ }
+
+ @Override
+ public int hashCode() {
+ return labels.get(0).getLexicalForm().hashCode();
+ }
+
+ /**
+ * If the default labels of two {@link Facet}s are equal, they are
considered as equal. Default label of a
+ * facet is obtained by passing a <code>null</code> parameter to {@link
#getLabel(Locale)} method.
+ */
+ @Override
+ public boolean equals(Object obj) {
+ if (obj instanceof Facet) {
+ return this.getLabel(null).equals(((Facet) obj).getLabel(null));
+ } else {
+ return false;
+ }
+ }
+}
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/ConstrainedDocumentSet.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/ConstrainedDocumentSet.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/ConstrainedDocumentSet.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/ConstrainedDocumentSet.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2012 The Apache Software Foundation.
+ *
+ * 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.apache.stanbol.contenthub.servicesapi.search.featured;
+
+import java.util.List;
+import java.util.Set;
+
+import org.apache.clerezza.rdf.core.UriRef;
+import org.apache.stanbol.contenthub.servicesapi.search.SearchException;
+
+/**
+ * A set of documents that can be narrowed by applying {@link Constraint}s
that are grouped by {@link Facet}s.
+ * Instances of this class are immutable, narrowing and broadening return new
instances.
+ */
+public interface ConstrainedDocumentSet {
+ /**
+ * Returns the documents contained in this {@link ConstrainedDocumentSet}.
There is no defined order of
+ * the list, but implementations should keep the order stable as too allow
stateless pagination.
+ *
+ * Implementations may populate the list just when the respective elements
are accessed and implement
+ * size() to access optimized backend functionality. Clients must thus
take into account the possibility
+ * that the list changes while they are using it. For example the size
returned by List.size() may not
+ * match the actual number of elements when iterating throw it at a later
point in time. The iterate() as
+ * well as the subList(int,int) method are safe.
+ *
+ * @return the documents included in this {@link ConstrainedDocumentSet}
+ * @throws SearchException
+ */
+ List<UriRef> getDocuments() throws SearchException;
+
+ /**
+ * This method returns the {@link Set} of {@link Constraint}s which have
been used to obtain the documents
+ * included in this set.
+ *
+ * @return the constrains that apply to this ConstrainedDocumentSet (might
be empty)
+ */
+ Set<Constraint> getConstraints();
+
+ /**
+ * This method returns all possible {@link Facet}s together with all their
possible {@link Constraint}s
+ * that can be used to filter documents included in this set.
+ *
+ * @return the {@link Facet}s by which this {@link ConstrainedDocumentSet}
can be restricted.
+ */
+ Set<Facet> getFacets();
+
+ /**
+ * Note that the new set need not to be computed when this method is
called, the matching document might
+ * be computed when needed. So implimentations can provided efficient way
to allow a client to call
+ *
+ * <code>narrow(additionalConstraint).getDocuments().size()</code>
+ *
+ * Creates a new {@link ConstrainedDocumentSet} with the new set of {@link
Constraint} which is formed by
+ * adding the specified <code>constraint</code> the constraint set
returned by {@link #getConstraints()}.
+ *
+ * @param constraint
+ * the additional {@link Constraint} to apply
+ * @return the restricted {@link ConstrainedDocumentSet} by applying the
given additional
+ * <code>constraint</code>
+ * @throws SearchException
+ */
+ ConstrainedDocumentSet narrow(Constraint constraint) throws
SearchException;
+
+ /**
+ * Creates a new {@link ConstrainedDocumentSet} with the new set of {@link
Constraint}s which is formed by
+ * removing the specified <code>constraint</code> from the constraint set
returned by
+ * {@link #getConstraints()}.
+ *
+ * @param constraint
+ * the {@link Constraint} which must be member of the set
returned by {@link #getConstraints()}
+ * @return the broadened {@link ConstrainedDocumentSet} by removing the
given <code>constraint</code>.
+ * @throws SearchException
+ */
+ ConstrainedDocumentSet broaden(Constraint constraint) throws
SearchException;
+
+}
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Constraint.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Constraint.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Constraint.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Constraint.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2012 The Apache Software Foundation.
+ *
+ * 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.apache.stanbol.contenthub.servicesapi.search.featured;
+
+import org.apache.clerezza.rdf.core.Resource;
+
+/**
+ * {@link Constraint} is used while doing a search using {@link
FeaturedSearch} of Contenthub. It provides
+ * specifying additional restrictions other than the original query keyword
for the search operation. A
+ * constraint requires a document property to have a certain value. A document
property corresponds to a
+ * {@link Facet} and constraints are parts of facets. A constraint represents
one of the possible values of a
+ * facet.
+ *
+ * <p>
+ * For example, assume a document has a property <b>places</b> indicating the
related places with the
+ * document. This property corresponds to a facet and assume that this facet
has two values <b>Paris</b> and
+ * <b>London</b>. Each such value of a facet is represented with a separate
constraint.
+ * </p>
+ */
+public interface Constraint {
+ /**
+ * @return the {@link Facet} this constraint relates to.
+ */
+ Facet getFacet();
+
+ /**
+ * This method returns the value of this {@link Constraint}. Documents
matching this constraint have the
+ * value to be returned as value of one of their properties. That certain
document property corresponds to
+ * the {@link Facet} which is associated with this constraint.
+ *
+ * @return the value of this constraint as a {@link Resource}.
+ */
+ String getValue();
+}
Added:
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Facet.java
URL:
http://svn.apache.org/viewvc/incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Facet.java?rev=1325635&view=auto
==============================================================================
---
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Facet.java
(added)
+++
incubator/stanbol/branches/faceted-browsing/contenthub/servicesapi/src/main/java/org/apache/stanbol/contenthub/servicesapi/search/featured/Facet.java
Fri Apr 13 07:29:53 2012
@@ -0,0 +1,46 @@
+/*
+ * Copyright 2012 The Apache Software Foundation.
+ *
+ * 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.apache.stanbol.contenthub.servicesapi.search.featured;
+
+import java.util.Locale;
+import java.util.Set;
+
+/**
+ * A {@link Facet} is an aspect by which the {@link ConstrainedDocumentSet}
can be narrowed. Facets correspond
+ * to properties of documents and they are used in the search operations in
{@link FeaturedSearch} of
+ * Contenthub. Facets are considered as equal if their default labels are the
same. Default labels of facets
+ * are obtained by providing <code>null</code> to {@link #getLabel(Locale)}.
+ */
+public interface Facet {
+
+ /**
+ * This methods return all possible values regarding this facet wrapped in
a {@link Set} of
+ * {@link Constraint}s. Constraints are used to filter search results
based on certain values of facets.
+ *
+ * @return a {@link Set} of constraints that reduce the document to a
non-empty set
+ */
+ Set<Constraint> getConstraints();
+
+ /**
+ * Returns a label for this {@link Facet} based on the given {@link
Locale} preference.
+ *
+ * @param locale
+ * the desired {@link Locale} or <code>null</code> if no
preference.
+ * @return a label for this facet
+ */
+ String getLabel(Locale locale);
+
+}
\ No newline at end of file
