net.sf.eBusx.geo.LineString Maven / Gradle / Ivy
//
// Copyright 2021 Charles W. Rapp
//
// 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 net.sf.eBusx.geo;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
import net.sf.eBus.messages.EField;
import net.sf.eBus.util.Validator;
/**
* Contains two or more {@link Position}s used to define a
* "line". The reason for the quotes is the the points may
* form a figure which may cross itself, form a closed polygon,
* or define a curve. It does not have to define a straight
* line.
*
* @author Charles W. Rapp
*/
public final class LineString
extends EField
{
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Constants.
//
/**
* Serialization version identifier.
*/
private static final long serialVersionUID = 0x500700L;
//-----------------------------------------------------------
// Locals.
//
/**
* The multiple points defining this line string.
*/
public final Position[] positions;
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Constructor is private because a line string instance may
* only be created using a builder.
* @param builder builder containing valid line string
* configuration.
*/
private LineString(final Builder builder)
{
super (builder);
positions = builder.positions();
} // end of LineString(Builder)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
/**
* Returns a single text line containing all the line string
* positions.
* @return text containing line string positions.
*/
@Override
public String toString()
{
final int numPos = positions.length;
String sep = "";
final StringBuilder retval = new StringBuilder();
retval.append("[pos={");
for (int i = 0; i < numPos; ++i, sep = ", ")
{
retval.append(sep).append(positions[i]);
}
return (retval.append("}]").toString());
} // end of toString()
/**
* Returns {@code true} if {@code o} is a
* non-{@code null Linestring} with a position array equaling
* {@code this LineString} position array. Otherwise returns
* {@code false}.
* @param o comparison object.
* @return {@code true} if {@code o} is a
* non-{@code null Linestring} with a position array equaling
* {@code this LineString} position array.
*/
@Override
public boolean equals(final Object o)
{
boolean retcode = (this == o);
if (!retcode && o instanceof LineString)
{
retcode =
Arrays.equals(
positions, ((LineString) o).positions);
}
return (retcode);
} // end of equals(Object)
/**
* Returns hash code of contained positions.
* @return contained positions hash code.
*/
@Override
public int hashCode()
{
return (Objects.hash((Object[]) positions));
} // end of hashCode()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Get Methods.
//
/**
* Returns {@code true} if this line string has three or
* more positions and the first and last position are
* equal; otherwise returns {@code false}
* @return {@code true} if contains > 2 positions and
* the first and last positions are equal.
*/
public boolean isClosed()
{
final int numPos = positions.length;
return (numPos > 2 &&
positions[0].equals(positions[numPos - 1]));
} // end of isClosed()
// TODO: need method isSelfIntersecting() returning true
// if linestring intersects itself.
//
// end of Get Methods.
//-----------------------------------------------------------
/**
* Returns a new line string builder instance.
* @return new line string builder instance.
*/
public static Builder builder()
{
return (new Builder());
} // end of builder()
//---------------------------------------------------------------
// Inner classes.
//
/**
* Builder class used to create {@code LineString}
* instances. A {@code Builder} instance is obtained by
* calling {@link #builder()} method.
*/
public static final class Builder
extends EField.Builder
{
//-----------------------------------------------------------
// Member data.
//
//-------------------------------------------------------
// Constants.
//
private static final String POSITIONS_ERROR =
"positions is null";
//-------------------------------------------------------
// Locals.
//
private final List mPositions;
//-----------------------------------------------------------
// Member methods.
//
//-------------------------------------------------------
// Constructors.
//
private Builder()
{
super (LineString.class);
mPositions = new ArrayList<>();
} // end of Builder()
//
// end of Constructors.
//-------------------------------------------------------
//-------------------------------------------------------
// Builder Method Overrides.
//
/**
* Verifies that this line string has at least two
* positions.
* @param problems append detected problems to this
* list.
* @return {@code problems} to allow for method chaining.
*/
@Override
protected Validator validate(Validator problems)
{
return (super.validate(problems)
.requireTrue(mPositions.size() >= 2,
"mPositions",
"positions size < 2"));
// TODO: check if line string is
// self-intersecting?
} // end of validate(Validator)
/**
* Returns a new {@code LineString} instance created from
* this builder's validated settings.
* @return new line string instance.
*/
@Override
public LineString buildImpl()
{
return (new LineString(this));
} // end of buildImpl()
//
// end of Builder Method Overrides.
//-------------------------------------------------------
//-------------------------------------------------------
// Get Methods.
//
/**
* Returns positions list as an array.
* @return positions array.
*/
private Position[] positions()
{
return (
mPositions.toArray(
new Position[mPositions.size()]));
} // end of positions()
//
// end of Get Methods.
//-------------------------------------------------------
//-------------------------------------------------------
// Set Methods.
//
/**
* Appends position to positions list.
* @param pos append this position.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code pos} is {@code null}.
*
* @see #addAll(Position[])
* @see #addAll(Collection)
* @see #positions(Position[])
*/
public Builder add(final Position pos)
{
mPositions.add(
Objects.requireNonNull(pos, "pos is null"));
return (this);
} // end of add(Position)
/**
* Appends position array to positions list.
* @param positions append all positions to list.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code positions} is {@code null}.
*
* @see #add(Position)
* @see #addAll(Collection)
* @see #positions(Position[])
*/
public Builder addAll(final Position[] positions)
{
Collections.addAll(
mPositions,
Objects.requireNonNull(
positions, POSITIONS_ERROR));
return (this);
} // end of addAll(Position[])
/**
* Appends position collection to positions list.
* @param positions append all positions to list.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code positions} is {@code null}.
*
* @see #add(Position)
* @see #addAll(Position[])
* @see #positions(Position[])
*/
public Builder addAll(final Collection positions)
{
mPositions.addAll(
Objects.requireNonNull(
positions, POSITIONS_ERROR));
return (this);
} // end of addAll(Collection<>)
/**
* Sets positions list to the given position values. Note
* that all previously added positions are removed from
* the list prior to adding these positions but
* after verifying that positions array is not
* {@code null}.
* @param positions set position list to this array.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code positions} is {@code null}. If this
* exception is thrown then positions list is unchanged.
*
* @see #add(Position)
* @see #addAll(Position[])
* @see #addAll(Collection)
*/
public Builder positions(final Position[] positions)
{
Objects.requireNonNull(positions, POSITIONS_ERROR);
mPositions.clear();
Collections.addAll(mPositions, positions);
return (this);
} // end of positions(Position[])
//
// end of Set Methods.
//-------------------------------------------------------
} // end of class Builder
} // end of class LineString