27622721129

Committed 16 Jun 2026 01:55PM UTC coverage: 26.963% (+6.3%) from 20.697%

Build # 27622721129

Build Type

Pull #483

github

Committed by

web-flow

Commit Message

Merge 73a4d0fe1 into 663f14f46

Pull Request Pull Request #483: Space/resource About pages, ref-aware spaces, and magic query params

Coverage Stats

1542 of 6717 branches covered (22.96%)

Branch coverage included in aggregate %.

3407 of 11638 relevant lines covered (29.27%)

4.31 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

10.67

src/main/java/com/knowledgepixels/nanodash/View.java

package com.knowledgepixels.nanodash;

import com.knowledgepixels.nanodash.template.Template;
import com.knowledgepixels.nanodash.template.TemplateData;
import com.knowledgepixels.nanodash.vocabulary.KPXL_TERMS;
import org.apache.commons.lang3.tuple.Pair;
import org.eclipse.rdf4j.model.IRI;
import org.eclipse.rdf4j.model.Literal;
import org.eclipse.rdf4j.model.Statement;
import org.eclipse.rdf4j.model.vocabulary.DCTERMS;
import org.eclipse.rdf4j.model.vocabulary.RDF;
import org.eclipse.rdf4j.model.vocabulary.RDFS;
import org.nanopub.Nanopub;
import org.nanopub.NanopubUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.common.cache.Cache;
import com.google.common.cache.CacheBuilder;

import java.io.Serializable;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.TimeUnit;

/**
 * A class representing a Resource View.
 */
public class View implements Serializable {

    private static final Logger logger = LoggerFactory.getLogger(View.class);
    private static final Set<IRI> supportedViewTypes = Set.of(
            KPXL_TERMS.TABULAR_VIEW,
            KPXL_TERMS.LIST_VIEW,
            KPXL_TERMS.PLAIN_PARAGRAPH_VIEW,
            KPXL_TERMS.NANOPUB_SET_VIEW,
            KPXL_TERMS.ITEM_LIST_VIEW
    );

    static Map<IRI, Integer> columnWidths = new HashMap<>();

    static {
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_1_OF_12, 1);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_2_OF_12, 2);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_3_OF_12, 3);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_4_OF_12, 4);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_5_OF_12, 5);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_6_OF_12, 6);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_7_OF_12, 7);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_8_OF_12, 8);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_9_OF_12, 9);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_10_OF_12, 10);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_11_OF_12, 11);
        columnWidths.put(KPXL_TERMS.COLUMN_WIDTH_12_OF_12, 12);
    }

    private static final Cache<String, View> views = CacheBuilder.newBuilder()
        .maximumSize(5_000)
        .expireAfterAccess(24, TimeUnit.HOURS)
        .build();

    /**
     * Memo of latest-version resolutions: view id (as passed to {@link #get(String)})
     * to the resolution time and the View it resolved to. Entries are served as
     * long as they live; one older than {@link #REFRESH_RESOLUTION_AFTER_MS} is
     * served stale while a background re-resolution runs (stale-while-revalidate,
     * like {@link ApiCache}), so a superseding view nanopub is picked up on a
     * later render without {@link #get(String)} ever blocking on the network
     * once an entry exists.
     */
    private static final Cache<String, Pair<Long, View>> latestResolvedViews = CacheBuilder.newBuilder()
        .maximumSize(5_000)
        .expireAfterAccess(24, TimeUnit.HOURS)
        .build();

    /**
     * Age after which a memoized latest-version resolution is re-resolved in the
     * background; mirrors the freshness window of
     * {@link QueryApiAccess#getLatestVersionId(String)}.
     */
    private static final long REFRESH_RESOLUTION_AFTER_MS = 1000 * 60;

    /**
     * Ids whose latest-version resolution is currently being refreshed in the
     * background, so concurrent renders don't pile up duplicate refreshes.
     */
    private static final Set<String> refreshingViews = ConcurrentHashMap.newKeySet();

    /**
     * Indicates whether {@link #get(String)} would currently return without
     * network access, i.e. a latest-version resolution is memoized for this id
     * (possibly stale, in which case get() serves it while refreshing in the
     * background). Used to decide between constructing a view-based panel
     * directly and deferring it to a lazy-loading AJAX request.
     *
     * @param id the ID of the View
     * @return true if {@link #get(String)} currently returns without blocking
     */
    public static boolean isCached(String id) {
        return latestResolvedViews.getIfPresent(id) != null;
    }

    /**
     * Get a View by its ID, resolving to the latest version (following the
     * supersedes chain).
     *
     * @param id the ID of the View
     * @return the View object
     */
    public static View get(String id) {
        return get(id, true);
    }

    /**
     * Get a View by its ID.
     *
     * @param id            the ID of the View
     * @param resolveLatest if true, follow the supersedes chain to load the latest
     *                      version of the view; if false, load exactly the given
     *                      version without a latest-version lookup. Pass false when
     *                      the caller already holds a latest-resolved IRI (e.g. from
     *                      the get-view-displays query, which now resolves it
     *                      server-side) to avoid a redundant network round-trip.
     * @return the View object
     */
    public static View get(String id, boolean resolveLatest) {
        String npId = id.replaceFirst("^(.*[^A-Za-z0-9-_]RA[A-Za-z0-9-_]{43})[^A-Za-z0-9-_].*$", "$1");
        if (!resolveLatest) {
            return getExactVersion(id, npId);
        }
        Pair<Long, View> memo = latestResolvedViews.getIfPresent(id);
        if (memo != null) {
            if (System.currentTimeMillis() - memo.getLeft() > REFRESH_RESOLUTION_AFTER_MS) {
                triggerResolutionRefresh(id, npId);
            }
            return memo.getRight();
        }
        View resolved = resolveLatestVersion(id, npId);
        if (resolved != null) {
            latestResolvedViews.put(id, Pair.of(System.currentTimeMillis(), resolved));
        }
        return resolved;
    }

    /**
     * Resolves a view id to the latest version of its view definition by
     * following the supersedes chain, falling back to the exact given version
     * if the lookup fails or doesn't yield a single embedded view IRI. This is
     * the network-touching part of {@link #get(String)}.
     */
    private static View resolveLatestVersion(String id, String npId) {
        // Automatically selecting latest version of view definition:
        // TODO This should be made configurable at some point, so one can make it a fixed version.
        try {
            String latestNpId = QueryApiAccess.getLatestVersionId(npId);
            if (!latestNpId.equals(npId)) {
                Nanopub np = Utils.getAsNanopub(latestNpId);
                if (np != null) {
                    Set<String> embeddedIris = NanopubUtils.getEmbeddedIriIds(np);
                    if (embeddedIris.size() == 1) {
                        String latestId = embeddedIris.iterator().next();
                        View cached = views.getIfPresent(latestId);
                        if (cached == null) {
                            cached = new View(latestId, np);
                            views.put(latestId, cached);
                        }
                        return cached;
                    }
                }
            }
        } catch (Exception ex) {
            logger.error("Error resolving latest version for view: {}", id, ex);
        }
        return getExactVersion(id, npId);
    }

    /**
     * Loads the view exactly as given, without a latest-version lookup.
     */
    private static View getExactVersion(String id, String npId) {
        Nanopub np = Utils.getAsNanopub(npId);
        View cached = views.getIfPresent(id);
        if (cached == null) {
            try {
                cached = new View(id, np);
                views.put(id, cached);
            } catch (Exception ex) {
                logger.error("Couldn't load nanopub for resource: {}", id, ex);
            }
        }
        return cached;
    }

    /**
     * Re-resolves a stale memoized latest-version resolution in the background.
     * The stale value keeps being served meanwhile; on failure it is re-stamped
     * with the current time, so failing lookups are retried at most once per
     * {@link #REFRESH_RESOLUTION_AFTER_MS} rather than on every render.
     */
    private static void triggerResolutionRefresh(String id, String npId) {
        if (!refreshingViews.add(id)) return;
        NanodashThreadPool.submit(() -> {
            try {
                View resolved = resolveLatestVersion(id, npId);
                if (resolved == null) {
                    Pair<Long, View> previous = latestResolvedViews.getIfPresent(id);
                    resolved = (previous == null ? null : previous.getRight());
                }
                if (resolved != null) {
                    latestResolvedViews.put(id, Pair.of(System.currentTimeMillis(), resolved));
                }
            } finally {
                refreshingViews.remove(id);
            }
        });
    }

    private String id;
    private Nanopub nanopub;
    private IRI viewKind;
    private String label;
    private String title = "View";
    private GrlcQuery query;
    private String queryField = "resource";
    private Integer pageSize;
    private Integer displayWidth;
    private String structuralPosition;
    private List<IRI> viewResultActionList = new ArrayList<>();
    private List<IRI> viewEntryActionList = new ArrayList<>();
    private Set<IRI> appliesToClasses = new HashSet<>();
    private Set<IRI> appliesToNamespaces = new HashSet<>();
    private Map<IRI, Template> actionTemplateMap = new HashMap<>();
    private Map<IRI, String> actionTemplateTargetFieldMap = new HashMap<>();
    private Map<IRI, IRI> actionTemplateTypeMap = new HashMap<>();
    private Map<IRI, String> actionTemplatePartFieldMap = new HashMap<>();
    private Map<IRI, List<String>> actionTemplateQueryMappingsMap = new HashMap<>();
    private Map<IRI, String> labelMap = new HashMap<>();
    private IRI viewType;
    private Map<IRI, Set<IRI>> actionVisibleToMap = new HashMap<>();

    private View(String id, Nanopub nanopub) {
        this.id = id;
        this.nanopub = nanopub;
        List<IRI> actionList = new ArrayList<>();
        boolean viewTypeFound = false;
        for (Statement st : nanopub.getAssertion()) {
            if (st.getSubject().stringValue().equals(id)) {
                if (st.getPredicate().equals(RDF.TYPE)) {
                    if (st.getObject().equals(KPXL_TERMS.RESOURCE_VIEW)) {
                        viewTypeFound = true;
                    }
                    if (st.getObject() instanceof IRI objIri && supportedViewTypes.contains(objIri)) {
                        viewType = objIri;
                    }
                } else if (st.getPredicate().equals(DCTERMS.IS_VERSION_OF) && st.getObject() instanceof IRI objIri) {
                    viewKind = objIri;
                } else if (st.getPredicate().equals(RDFS.LABEL)) {
                    label = st.getObject().stringValue();
                } else if (st.getPredicate().equals(DCTERMS.TITLE)) {
                    title = st.getObject().stringValue();
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_VIEW_QUERY)) {
                    query = GrlcQuery.get(st.getObject().stringValue());
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_VIEW_QUERY_TARGET_FIELD)) {
                    queryField = st.getObject().stringValue();
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_VIEW_ACTION) && st.getObject() instanceof IRI objIri) {
                    actionList.add(objIri);
                } else if (st.getPredicate().equals(KPXL_TERMS.APPLIES_TO_NAMESPACE) && st.getObject() instanceof IRI objIri) {
                    appliesToNamespaces.add(objIri);
                } else if (st.getPredicate().equals(KPXL_TERMS.APPLIES_TO_INSTANCES_OF) && st.getObject() instanceof IRI objIri) {
                    appliesToClasses.add(objIri);
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_VIEW_TARGET_CLASS) && st.getObject() instanceof IRI objIri) {
                    // Deprecated
                    appliesToClasses.add(objIri);
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_PAGE_SIZE) && st.getObject() instanceof Literal objL) {
                    try {
                        pageSize = Integer.parseInt(objL.stringValue());
                    } catch (NumberFormatException ex) {
                        logger.error("Invalid page size value: {}", objL.stringValue(), ex);
                    }
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_DISPLAY_WIDTH) && st.getObject() instanceof IRI objIri) {
                    displayWidth = columnWidths.get(objIri);
                } else if (st.getPredicate().equals(KPXL_TERMS.HAS_STRUCTURAL_POSITION) && st.getObject() instanceof Literal objL) {
                    structuralPosition = objL.stringValue();
                }
            } else if (st.getPredicate().equals(KPXL_TERMS.HAS_ACTION_TEMPLATE)) {
                Template template = TemplateData.get().getTemplate(st.getObject().stringValue());
                actionTemplateMap.put((IRI) st.getSubject(), template);
            } else if (st.getPredicate().equals(KPXL_TERMS.HAS_ACTION_TEMPLATE_TARGET_FIELD)) {
                putUnlessVoid(actionTemplateTargetFieldMap, (IRI) st.getSubject(), st.getObject().stringValue());
            } else if (st.getPredicate().equals(KPXL_TERMS.HAS_ACTION_TEMPLATE_PART_FIELD)) {
                putUnlessVoid(actionTemplatePartFieldMap, (IRI) st.getSubject(), st.getObject().stringValue());
            } else if (st.getPredicate().equals(KPXL_TERMS.HAS_ACTION_TEMPLATE_QUERY_MAPPING)) {
                // Repeatable: an action may declare several query mappings (e.g. derive
                // maps both the row np and the local pubkey). "void" means "none".
                String mapping = st.getObject().stringValue();
                if (!"void".equals(mapping)) {
                    actionTemplateQueryMappingsMap.computeIfAbsent((IRI) st.getSubject(), k -> new ArrayList<>()).add(mapping);
                }
            } else if (st.getPredicate().equals(KPXL_TERMS.IS_VISIBLE_TO) && st.getObject() instanceof IRI objIri) {
                // Per-action visibility: gen:isVisibleTo on an action node restricts
                // that action button to viewers holding the given role tier or
                // specific role. See docs/role-specific-views.md.
                actionVisibleToMap.computeIfAbsent((IRI) st.getSubject(), k -> new HashSet<>()).add(objIri);
            } else if (st.getPredicate().equals(RDFS.LABEL)) {
                labelMap.put((IRI) st.getSubject(), st.getObject().stringValue());
            } else if (st.getPredicate().equals(RDF.TYPE)) {
                if (st.getObject().equals(KPXL_TERMS.VIEW_ACTION) || st.getObject().equals(KPXL_TERMS.VIEW_ENTRY_ACTION)) {
                    actionTemplateTypeMap.put((IRI) st.getSubject(), (IRI) st.getObject());
                }
            }
        }
        for (IRI actionIri : actionList) {
            if (actionTemplateTypeMap.containsKey(actionIri) && actionTemplateTypeMap.get(actionIri).equals(KPXL_TERMS.VIEW_ENTRY_ACTION)) {
                viewEntryActionList.add(actionIri);
            } else {
                viewResultActionList.add(actionIri);
            }
        }
        if (!viewTypeFound) throw new IllegalArgumentException("Not a proper resource view nanopub: " + id);
        if (query == null) throw new IllegalArgumentException("Query not found: " + id);
    }

    /**
     * Stores an action-field value unless it is the {@code "void"} sentinel.
     * View-creation templates can't leave a statement optional inside a repeated
     * action group, so views carry every action field, with {@code "void"} for the
     * not-applicable ones (its presence is what lets Nanodash repopulate the action
     * group when superseding a view). It is treated here as absent — so e.g. a
     * "void" part field never becomes a bogus {@code param_void}.
     */
    private static void putUnlessVoid(Map<IRI, String> map, IRI key, String value) {
        if (value != null && !value.equals("void")) {
            map.put(key, value);
        }
    }

    /**
     * Gets the ID of the View.
     *
     * @return the ID of the View
     */
    public String getId() {
        return id;
    }

    /**
     * Gets the Nanopub defining this View.
     *
     * @return the Nanopub defining this View
     */
    public Nanopub getNanopub() {
        return nanopub;
    }

    public IRI getViewKindIri() {
        return viewKind;
    }

    /**
     * Gets the label of the View.
     *
     * @return the label of the View
     */
    public String getLabel() {
        return label;
    }

    /**
     * Gets the title of the View.
     *
     * @return the title of the View
     */
    public String getTitle() {
        return title;
    }

    /**
     * Gets the GrlcQuery associated with the View.
     *
     * @return the GrlcQuery associated with the View
     */
    public GrlcQuery getQuery() {
        return query;
    }

    /**
     * Gets the query field of the View.
     *
     * @return the query field
     */
    public String getQueryField() {
        return queryField;
    }

    /**
     * Returns the preferred page size.
     *
     * @return page size (0 = everything on first page)
     */
    public Integer getPageSize() {
        return pageSize;
    }

    public Integer getDisplayWidth() {
        return displayWidth;
    }

    public String getStructuralPosition() {
        return structuralPosition;
    }

    /**
     * Gets the visibility restriction declared on a given action node via
     * {@code gen:isVisibleTo}: the set of role-tier or specific-role IRIs a viewer
     * must hold for that action button to be shown. An empty set means the action
     * is visible to everyone (subject to the existing button-list routing).
     *
     * @param actionIri the action IRI (a result or entry action of this view)
     * @return the set of {@code gen:isVisibleTo} IRIs for that action (never null)
     */
    public Set<IRI> getActionVisibleTo(IRI actionIri) {
        return actionVisibleToMap.getOrDefault(actionIri, Collections.emptySet());
    }

    /**
     * Gets the list of action IRIs associated with the View.
     *
     * @return the list of action IRIs
     */
    public List<IRI> getViewResultActionList() {
        return viewResultActionList;
    }

    public List<IRI> getViewEntryActionList() {
        return viewEntryActionList;
    }

    /**
     * Gets the Template for a given action IRI.
     *
     * @param actionIri the action IRI
     * @return the Template for the action IRI
     */
    public Template getTemplateForAction(IRI actionIri) {
        return actionTemplateMap.get(actionIri);
    }

    /**
     * Gets the template field for a given action IRI.
     *
     * @param actionIri the action IRI
     * @return the template field for the action IRI
     */
    public String getTemplateTargetFieldForAction(IRI actionIri) {
        return actionTemplateTargetFieldMap.get(actionIri);
    }

    public String getTemplatePartFieldForAction(IRI actionIri) {
        return actionTemplatePartFieldMap.get(actionIri);
    }

    /**
     * Gets the query mappings declared for an action: each is {@code "col:target"},
     * mapping result column {@code col} to template parameter {@code param_target}
     * — or, when {@code target} begins with {@code @}, to the raw URL parameter
     * {@code target} (without the {@code param_} prefix), used for fill-mode keys
     * such as {@code @derive-a} / {@code @supersede}. An entry action applies all
     * of these per row; see docs/magic-query-params.md.
     *
     * @param actionIri the action IRI
     * @return the list of mappings (never null; empty if none)
     */
    public List<String> getTemplateQueryMappings(IRI actionIri) {
        List<String> result = new ArrayList<>();
        for (String literal : actionTemplateQueryMappingsMap.getOrDefault(actionIri, Collections.emptyList())) {
            result.addAll(parseMappingLiteral(literal));
        }
        return result;
    }

    /**
     * Splits a query-mapping literal into individual {@code "col:target"} mappings
     * on whitespace. Multiple mappings share a single literal because a
     * view-creation template cannot repeat a statement inside its repeated action
     * group — e.g. {@code "np:nanopubToBeRetracted"} or
     * {@code "derive_target:@derive-a local_pubkey:public-key__.1"}.
     *
     * @param literal the mapping literal (may be null/blank/"void")
     * @return the individual mappings (never null; empty if none)
     */
    public static List<String> parseMappingLiteral(String literal) {
        List<String> mappings = new ArrayList<>();
        if (literal == null || literal.isBlank()) return mappings;
        for (String m : literal.trim().split("\\s+")) {
            if (!m.isEmpty() && !"void".equals(m)) mappings.add(m);
        }
        return mappings;
    }

    /**
     * Gets the set of query result columns that serve only as <em>sources</em> for
     * this view's action query mappings (the {@code col} part of each
     * {@code "col:target"} mapping, across all actions). These columns carry
     * action data — conditional targets, the local-key bundle — not row content, so
     * the result builders skip them when rendering visible columns. A column that
     * happens to be both a display column and a mapping source would also be hidden;
     * map a duplicated/aliased column instead if you need to show one.
     *
     * @return the set of mapping-source column names (never null)
     */
    public Set<String> getActionMappingSourceColumns() {
        Set<String> columns = new HashSet<>();
        for (IRI actionIri : actionTemplateQueryMappingsMap.keySet()) {
            for (String mapping : getTemplateQueryMappings(actionIri)) {
                int idx = mapping.indexOf(':');
                if (idx > 0) columns.add(mapping.substring(0, idx));
            }
        }
        return columns;
    }

    /**
     * Gets the first query mapping for an action, or null. Kept for result-action
     * callers that pass a single {@code values-from-query-mapping}.
     *
     * @param actionIri the action IRI
     * @return the first mapping, or null
     */
    public String getTemplateQueryMapping(IRI actionIri) {
        List<String> mappings = actionTemplateQueryMappingsMap.get(actionIri);
        return (mappings == null || mappings.isEmpty()) ? null : mappings.get(0);
    }

    /**
     * Gets the label for a given action IRI.
     *
     * @param actionIri the action IRI
     * @return the label for the action IRI
     */
    public String getLabelForAction(IRI actionIri) {
        return labelMap.get(actionIri);
    }

    public boolean appliesTo(String resourceId, Set<IRI> classes) {
        for (IRI namespace : appliesToNamespaces) {
            if (resourceId.startsWith(namespace.stringValue())) return true;
        }
        if (classes != null) {
            for (IRI c : classes) {
                if (appliesToClasses.contains(c)) return true;
            }
        }
        return false;
    }

    /**
     * Checks if the View has target classes.
     *
     * @return true if the View has target classes, false otherwise
     */
    public boolean appliesToClasses() {
        return !appliesToClasses.isEmpty();
    }

    /**
     * Checks if the View has a specific target class.
     *
     * @param targetClass the target class IRI
     * @return true if the View has the target class, false otherwise
     */
    public boolean appliesToClass(IRI targetClass) {
        return appliesToClasses.contains(targetClass);
    }

    @Override
    public String toString() {
        return id;
    }

    /**
     * Gets the view type of the View.
     *
     * @return the view type mode IRI
     */
    public IRI getViewType() {
        return viewType;
    }

    /**
     * Get the supported view types.
     *
     * @return a set of supported view type IRIs
     */
    public static Set<IRI> getSupportedViewTypes() {
        return supportedViewTypes;
    }

}

knowledgepixels / nanodash / 27622721129

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous