LangFacetValue.java

/*
 * Copyright (c) 2007-2026 MetaSolutions AB
 *
 * 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.entrystore.repository.util;

import org.eclipse.rdf4j.model.Literal;
import org.eclipse.rdf4j.model.util.Literals;

import java.util.IllformedLocaleException;

/**
 * One term of the internal {@code metadata.predicate.literal_l.*} Solr field family: the label of a literal together
 * with its normalised language tag. The family is the companion of {@code metadata.predicate.literal_s.*}: the REST
 * layer facets on it server-side to filter labels by language. It is
 * never accepted from clients as a facet or sort field and never returned to them.
 *
 * <p>The indexer stores every literal whose label is at most {@link #MAX_LABEL_LENGTH} characters as
 * {@code label + U+001F + language} (empty language for untagged and typed literals), so one Solr term exists per
 * distinct (label, language) pair. The separator is always present and a BCP 47 language tag can never contain it,
 * so {@link #decode(String)} splits at the last occurrence and recovers a label that itself contains the separator.
 * Language tags are normalised with {@link Literals#normalizeLanguageTag(String)} at index time, so {@code en-gb}
 * and {@code en-GB} share one term.
 *
 * @param label the lexical form of the literal
 * @param lang  the normalised language tag, or {@code null} when the literal has none
 */
public record LangFacetValue(String label, String lang) {

	public static final String FIELD_PREFIX = "metadata.predicate.literal_l.";

	/** Labels longer than this get no companion term: they are descriptions, not facet values. */
	public static final int MAX_LABEL_LENGTH = 256;

	private static final String RELATED_PREFIX = "related.";

	private static final String LITERAL_S_PREFIX = "metadata.predicate.literal_s.";

	private static final char SEPARATOR = '\u001F';

	private static final String SEPARATOR_REGEX = "\\x1F";

	public LangFacetValue {
		if (lang != null && lang.isEmpty()) {
			lang = null;
		}
	}

	/**
	 * A tag containing the separator is dropped and the literal encoded as untagged. {@code normalizeLanguageTag}
	 * keeps an ill-formed tag verbatim, and a client-supplied {@code lang} reaches {@code createLiteral} unvalidated
	 * ({@code RDFJSON}), so without this {@link #decode(String)} would split at the tag's own separator and report
	 * part of it as the label.
	 */
	public static String encode(Literal literal) {
		String lang = literal.getLanguage().map(LangFacetValue::normalizeLanguageTag).orElse("");
		if (lang.indexOf(SEPARATOR) >= 0) {
			lang = "";
		}
		return literal.getLabel() + SEPARATOR + lang;
	}

	public static boolean exceedsLabelCap(String label) {
		return label.length() > MAX_LABEL_LENGTH;
	}

	/**
	 * A term without a separator degrades to a label-only value, so the response path never throws on an
	 * unexpected term.
	 */
	public static LangFacetValue decode(String term) {
		int separatorIndex = term.lastIndexOf(SEPARATOR);
		if (separatorIndex < 0) {
			return new LangFacetValue(term, null);
		}
		return new LangFacetValue(term.substring(0, separatorIndex), term.substring(separatorIndex + 1));
	}

	public static boolean isLangFacetField(String fieldName) {
		return fieldName != null
				&& (fieldName.startsWith(FIELD_PREFIX) || fieldName.startsWith(RELATED_PREFIX + FIELD_PREFIX));
	}

	/**
	 * The internal companion of a client-visible literal facet field: {@code [related.]metadata.predicate.literal_s.<tail>}
	 * maps to {@code [related.]metadata.predicate.literal_l.<tail>}. Every other field, including the
	 * {@code metadata.predicate.literal.} shorthand before its rewrite, yields {@code null}, so callers can test for a
	 * literal facet and derive its companion in one step.
	 */
	public static String companionField(String facetField) {
		if (facetField == null) {
			return null;
		}
		boolean related = facetField.startsWith(RELATED_PREFIX);
		String base = related ? facetField.substring(RELATED_PREFIX.length()) : facetField;
		if (!base.startsWith(LITERAL_S_PREFIX) || base.length() == LITERAL_S_PREFIX.length()) {
			return null;
		}
		String companion = FIELD_PREFIX + base.substring(LITERAL_S_PREFIX.length());
		return related ? RELATED_PREFIX + companion : companion;
	}

	/**
	 * Canonical BCP 47 casing via RDF4J ({@code en-gb} becomes {@code en-GB}, {@code SV} becomes {@code sv}). An
	 * ill-formed tag is kept verbatim rather than dropping the literal from the companion field.
	 */
	public static String normalizeLanguageTag(String tag) {
		try {
			return Literals.normalizeLanguageTag(tag);
		} catch (IllformedLocaleException e) {
			return tag;
		}
	}

	/**
	 * Full-string regex selecting the encoded terms of one language range, as RFC 4647 basic filtering: the label
	 * part, the separator, then either an empty tag (untagged labels are always included), the range itself, or the
	 * range followed by a subtag, so {@code en} selects {@code en} and {@code en-GB} but not {@code eng}. Only the
	 * language part is case-insensitive; the label part stays as case-sensitive as the client's {@code facetMatches}
	 * is on the client field, so adding {@code facetLang} can only narrow the labels.
	 *
	 * @param labelRegex the client's {@code facetMatches}, or null to accept any label
	 * @param range a normalised language tag, already restricted to {@code [A-Za-z0-9-]} by input validation and so
	 * free of regex metacharacters
	 */
	public static String languageMatchesRegex(String labelRegex, String range) {
		String label = labelRegex == null ? "[^" + SEPARATOR_REGEX + "]*" : "(?:" + labelRegex + ")";
		return label + SEPARATOR_REGEX + "(?i:|" + range + "|" + range + "-[^" + SEPARATOR_REGEX + "]*)";
	}
}