<commit_before>/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.sis.internal.map;

import java.util.Objects;
import org.apache.sis.storage.Query;
import org.apache.sis.storage.Resource;
import org.opengis.style.Style;


/**
 * Data (resource) associated to visual representation (symbology).
 * Layers are the key elements of a map: they link datas (given by a {@link Resource})
 * to their visual representation (defined by a {@link Style}).
 * The visual appearance of a layer should be similar with any rendering engine.
 * Some details may very because of different rendering strategies for label placements, 2D or 3D,
 * but the fundamentals aspect of each {@link org.opengis.feature.Feature} or
 * {@link org.opengis.coverage.Coverage} should be unchanged.
 *
 * <p>
 * NOTE: this class is a first draft subject to modifications.
 * </p>
 *
 * @author  <NAME> (Geomatys)
 * @version 2.0
 * @since   2.0
 * @module
 */
public class MapLayer extends MapItem {

    /** Identifies a change in the layer resource. */
    public static final String RESOURCE_PROPERTY = "resource";
    /** Identifies a change in the layer style. */
    public static final String STYLE_PROPERTY = "style";
    /** Identifies a change in the layer query. */
    public static final String QUERY_PROPERTY = "query";

    /**
     * Data to be rendered.
     */
    private Resource resource;

    /**
     * Visual representation of data.
     */
    private Style style;

    /**
     * User defined query.
     */
    private Query query;

    /**
     * Constructs an initially empty map layer.
     *
     * @todo Expect {@code Resource} and {@code Style} in argument, for discouraging
     *       the use of {@code MapLayer} with null resource and null style?
     */
    public MapLayer() {
    }

    /**
     * Returns the data (resource) represented by this layer.
     * The resource should be a {@link org.apache.sis.storage.DataSet},
     * but {@link org.apache.sis.storage.Aggregate} are also accepted.
     * The behavior in such case depends on the rendering engine.
     *
     * @return data to be rendered, or {@code null} is unavailable.
     */
    public Resource getResource() {
        return resource;
    }

    /**
     * Sets the data (resource) to be rendered.
     * The resource should never be null, still the null case is tolerated to indicate
     * that the layer should have existed but is unavailable for an unspecified reason.
     * This case may happen with processing or distant services resources.
     *
     * @param  resource  the new data, or {@code null} if unavailable.
     */
    public void setResource(Resource resource) {
        if (!Objects.equals(this.resource, resource)) {
            Resource old = this.resource;
            this.resource = resource;
            firePropertyChange(RESOURCE_PROPERTY, old, resource);
        }
    }

    /**
     * Returns the visual appearance of the data.
     * If the style is undefined, the behavior is left to the rendering engine.
     * It is expected that a default style should be used.
     *
     * @return description of data visual appearance, or {@code null} if unspecified.
     */
    public Style getStyle() {
        return style;
    }

    /**
     * Sets the visual appearance of the data.
     *
     * @param  style  description of data visual appearance, or {@code null} if unspecified.
     */
    public void setStyle(Style style) {
        if (!Objects.equals(this.style, style)) {
            Style old = this.style;
            this.style = style;
            firePropertyChange(STYLE_PROPERTY, old, style);
        }
    }

    /**
     * Returns the definition query for this layer.If no definition
     * query has been defined {@code null} is returned.
     * @return query, or {@code null} if unspecified.
     */
    public Query getQuery() {
        return query;
    }

    /**
     * Sets a filter query for this layer.
     *
     * <p>
     * Query filters should be used to reduce searched or displayed resource
     * when rendering or analyzing this layer.
     * </p>
     *
     * @param query the query for this layer, or {@code null} if unavailable.
     */
    public void setQuery(Query query) {
        if (!Objects.equals(this.query, query)) {
            Query old = this.query;
            this.query = query;
            firePropertyChange(QUERY_PROPERTY, old, query);
        }
    }
}<commit_msg>Edit javadoc for `MapLayer`. Note: we omit the message saying that this class may change in future version; this is the case of anything in "internal" packages.<commit_after>/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.sis.internal.map;

import java.util.Objects;
import org.opengis.style.Style;
import org.opengis.feature.Feature;
import org.opengis.coverage.Coverage;
import org.apache.sis.storage.Query;
import org.apache.sis.storage.Resource;
import org.apache.sis.storage.DataSet;
import org.apache.sis.storage.Aggregate;


/**
 * Data (resource) associated to visual representation (symbology).
 * Layers are the key elements of a map: they link data (given by {@link Resource}s) or a subset of
 * those data (filtered by {@link Query}) to their visual representation (defined by {@link Style}s).
 * The visual appearance of a layer should be similar with any rendering engine.
 * Some details may very because of different rendering strategies for label placements, 2D or 3D,
 * but the fundamentals aspect of each {@link Feature} or {@link Coverage} should be unchanged.
 *
 * @author  <NAME> (Geomatys)
 * @version 1.1
 * @since   1.1
 * @module
 */
public class MapLayer extends MapItem {
    /**
     * The {@value} property name, used for notifications about changes in map layer resource.
     * The resource provides the data to be rendered.
     * Associated values should be instances of {@link DataSet} or {@link Aggregate}.
     *
     * @see #getResource()
     * @see #setResource(Resource)
     */
    public static final String RESOURCE_PROPERTY = "resource";

    /**
     * The {@value} property name, used for notifications about changes in map layer query.
     * The query can filter resource data for rendering only a subset of available data.
     * Associated values are instances of {@link Query}.
     *
     * @see #getQuery()
     * @see #setQuery(Query)
     */
    public static final String QUERY_PROPERTY = "query";

    /**
     * The {@value} property name, used for notifications about changes in map layer style.
     * The style specifies the appearance of the filtered data to be rendered.
     * Associated values are instances of {@link Style}.
     *
     * @see #getStyle()
     * @see #setStyle(Style)
     */
    public static final String STYLE_PROPERTY = "style";

    /**
     * Data to be rendered, or {@code null} if unavailable.
     *
     * @see #RESOURCE_PROPERTY
     * @see #getResource()
     */
    private Resource resource;

    /**
     * Filter for rendering a subset of available data, or {@code null} if none.
     *
     * @see #QUERY_PROPERTY
     * @see #getQuery()
     */
    private Query query;

    /**
     * Visual representation of data, or {@code null} if none.
     *
     * @see #STYLE_PROPERTY
     * @see #getStyle()
     */
    private Style style;

    /**
     * Constructs an initially empty map layer.
     *
     * @todo Expect {@code Resource} and {@code Style} in argument, for discouraging
     *       the use of {@code MapLayer} with null resource and null style?
     */
    public MapLayer() {
    }

    /**
     * Returns the data (resource) represented by this layer.
     * The resource should be a {@link DataSet}, but {@link Aggregate} is also accepted.
     * The behavior in aggregate case depends on the rendering engine.
     *
     * @return data to be rendered, or {@code null} is unavailable.
     *
     * @see #RESOURCE_PROPERTY
     */
    public Resource getResource() {
        return resource;
    }

    /**
     * Sets the data (resource) to be rendered.
     * The resource should never be null, still the null case is tolerated to indicate
     * that the layer should have existed but is unavailable for an unspecified reason.
     * This case may happen with processing or distant services resources.
     *
     * <p>The given resource should be a {@link DataSet} or an {@link Aggregate} of data sets.
     * However this base class does not enforce those types. Subclasses may restrict the set
     * of resource types accepted by this method.</p>
     *
     * @param  newValue  the new data, or {@code null} if unavailable.
     */
    public void setResource(final Resource newValue) {
        final Resource oldValue = resource;
        if (!Objects.equals(oldValue, newValue)) {
            resource = newValue;
            firePropertyChange(RESOURCE_PROPERTY, oldValue, newValue);
        }
    }

    /**
     * Returns the filter for reducing the amount of data to render. Query filters can be
     * specified for rendering a smaller amount of data than what the resource can provide.
     * If the query is undefined, then all data will be rendered.
     *
     * @return filter for reducing data, or {@code null} for rendering all data.
     *
     * @see #QUERY_PROPERTY
     */
    public Query getQuery() {
        return query;
    }

    /**
     * Sets a filter for reducing the amount of data to render. If this method is never invoked, the default value
     * is {@code null}. If the given value is different than the previous value, then a change event is sent to all
     * listeners registered for the {@value #QUERY_PROPERTY} property.
     *
     * @param  newValue  filter for reducing data, or {@code null} for rendering all data.
     */
    public void setQuery(final Query newValue) {
        final Query oldValue = query;
        if (!Objects.equals(oldValue, newValue)) {
            query = newValue;
            firePropertyChange(QUERY_PROPERTY, oldValue, newValue);
        }
    }

    /**
     * Returns the visual appearance of the data.
     * If the style is undefined, the behavior is left to the rendering engine.
     * It is expected that a default style should be used.
     *
     * @return description of data visual appearance, or {@code null} if unspecified.
     */
    public Style getStyle() {
        return style;
    }

    /**
     * Sets the visual appearance of the data. If this method is never invoked, the default value is {@code null}.
     * If the given value is different than the previous value, then a change event is sent to all listeners
     * registered for the {@value #STYLE_PROPERTY} property.
     *
     * @param  newValue  description of data visual appearance, or {@code null} if unspecified.
     */
    public void setStyle(final Style newValue) {
        final Style oldValue = style;
        if (!Objects.equals(oldValue, newValue)) {
            style = newValue;
            firePropertyChange(STYLE_PROPERTY, oldValue, newValue);
        }
    }
}
{'fraction_non_alphanumeric': 0.08423067719550131, 'fraction_numerical': 0.0015952779771875249, 'mean_word_length': 2.681150910158544, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6204774', 'n_tokens_mistral': 3298, 'n_tokens_neox': 3231, 'n_words': 1461}