How to model Region and a point in that region? - oop

Question

I need to model a Region that has a contains(point) method. That method determines whether a point falls within the boundaries of the Region.
I currently see two implementations of Region:
One where the region is defined by a start and end postalcode.
One where the region is defined by a lat/lng and a radius.
Now, my main problem is how to define the interface for the contains() method.
Possible solution #1:
One easy solution is to let a point also be defined by a Region:
PostalcodeRegion implements Region
region = new PostalcodeRegion(postalStart: 1000, postalEnd: 2000);
point = new PostalcodeRegion(postalStart: 1234, postalEnd: 1234);
region.contains(point); // true
The interface could look like this:
Region
+ contains(Region region):bool
The problem with this is that the contains() method is not specific, and that we abuse Region to let it be something it is not: a Point.
Possible solution #2:
Or, we define a new point class:
PostalcodeRegion implements Region {}
PostalcodePoint implements Point {}
region = new PostalcodeRegion(postalStart: 1000, postalEnd: 2000);
point = new PostalcodePoint(postalCode: 1234);
region.contains(point); // true
Interface:
Region
+ contains(Point point)
There are several problems with this method:
contains() method is still not specific
There is a pointless Point concept. In and of itself it is/does nothing, it is just a marker interface.
Clarification:
Ok, so this is the first time I encounter where I provide my line of thinking, in the form of possible solutions, that is actually counter productive. My apologies.
Let me try and describe the use case: The system this use case is part of is used to handle insurance claims (amongst other things). When someone claims water damages from a leaking pipe f.e., this system handles the entire workflow from entry by the customer, all the way to sending a repair company etc to close the file.
Now, depending on circumstances, there are two ways to find eligible repair companies: by postal code, or by lat lng.
In the first case (postal code), we could find eligible repair companies with the following code:
region = new PostalCodeRegion(customer.postalCode - 500, customer.postalCode + 500)
region.contains(new PostalCodePoint(repairCompany1.postalCode))
region.contains(new PostalCodePoint(repairCompany2.postalCode))
Or, in the second case:
region = new LatLngRegion(customer.latLng, 50) // 50 km radius
region.contains(new LatLngPoint(repairCompany1.latLng))
region.contains(new LatLngPoint(repairCompany2.latLng))
I want to be able to safely pass around Regions and Points, so I can make sure they are Regions and Points. But I don't actually care about their sub-types.
One thing I would like, but I am not sure it is possible, is to not have to do a runtime check on the passed point in the contains() method. Preferably it would be enforced by contract that I get the correct data (fitting to the chosen Region implementation) to work with.
I'm mostly just thinking out loud. I am inclined to go with method #2, and do a runtime type check of the passed point var in contains() implementation.
I would like to hear some thoughts over one or the other, or even better: a new suggestion I haven't thought of.
It shouldn't be really relevant, but the target platform is PHP. So I can't use generics for example.

Answer 1

Given that a Region would have to operate on two abstractions that have nothing in common (Point and Postcode) then a generic interface is one way of crafting a clean strongly typed common interface, but you should question whether that abstraction is useful to model or not. As developers it's easy to get lost in too much abstractions e.g. maybe a Region<T> is just a Container<T>, etc. and all of a sudden the concepts you work with are nowhere to be found in your domain's Ubiquitous Language.
public interface Region<T> {
public boolean contains(T el);
}
class PostalRegion implements Region<Postcode> {
public boolean contains(Postcode el) { ... }
}
class GeographicRegion implements Region<Point> {
public boolean contains(Point el) { ... }
}
The issue with such question is that it's focusing on how to achieve a specific design rather than explaining the real business problem and that makes it difficult to judge whether or not the solution is appropriate or which alternate solution would.
How would the system leverage the common interface if such interface was implemented? Would it make the model easier to work with?
Since we are forced to assume a problem domain, here's a fictional scenario about developing a city zonage system (I know nothing about this domain so the example may be silly).
In the context of city zonage management, we have uniquely
identified regions that are defined by a postal code range and a
geographical area. We need a system that can answer whether or not a
postal code and/or a point is contained within a specific region.
That gives us a little more context to work with and come up with a model that can fulfill the needs.
We can assume that an application service such as RegionService could maybe look like:
class RegionService {
IRegionRepository regionRepository;
...
boolean regionContainsPoint(regionId, lat, lng) {
region = regionRepository.regionOfId(regionId);
return region.contains(new Point(lat, lng));
}
boolean regionContainsPostcode(regionId, postcode) {
region = regionRepository.regionOfId(regionId);
return region.contains(new Postcode(postcode));
}
}
Then, maybe the design would benefit from applying the Interface Segregation Principle (ISP) where you'd have a Locator<T> interface or explicit PostcodeLocator and PointLocator interfaces, implemented either by Region or other services and used by the RegionService or be a service of their own.
If answering the questions requires complex processing, etc. then maybe the logic should be extracted from a PostalRange and an Area. Applying the ISP would help keeping the design more flexible.
It's important to note that a domain model shines on the write side to protect invariants and compute complex rules & state transitions, but querying needs are often better expressed as stateless services that leverages powerful infrastructure components (e.g. database).
EDIT 1:
I had not realized you mentioned "no generics". Still leaving my answer there b/c I think it still gives good modeling insights and warns about not so useful abstractions. Always think about how the client will be using the API as it helps to determine the usefulness of an abstraction.
EDIT 2 (after clarification added):
It seems that the Specification Pattern could be a useful modeling tool here.
Customers could be said to have a repair company eligibility specification...
E.g.
class Customer {
...
repairCompanyEligibilitySpec() {
//The factory method for creating the specification doesn't have to be on the Customer
postalRange = new PostalRange(this.postalCode - 500, this.postCode + 500);
postalCodeWithin500Range = new PostalCodeWithinRange(postalRange);
locationWithin50kmRadius = new LocationWithinRadius(this.location, Distance.ofKm(50));
return postalCodeWithin500Range.and(locationWithin50kmRadius);
}
}
//Usage
repairCompanyEligibilitySpec = customer.repairCompanyEligibilitySpec();
companyEligibleForRepair = repairCompanyEligibilitySpec.isSatisfiedBy(company);
Note that I haven't really understood what you mean by "I want to be able to safely pass around Regions and Points" or at least failed to understand why this requires a common interface so perhaps the proposed design wouldn't be suitable. Making the policy/rule/spec explicit has several advantages and the specification pattern is easily extensible to support features such as describing why a company was not eligible, etc.
e.g.
unsatisfiedSpec = repairCompanyEligibilitySpec.remainderUnsatisfiedBy(company);
reasonUnsatisfied = unsatisfiedSpec.describe();
Ultimately the specification itself doesn't have to implement the operations. You could use the Visitor Pattern in order to add new operations to a set of specifications and/or to segregate operations by logical layer.

Answer 2

I think it's better not to have the implementation of contains in the data object and to create a seperate class for each of the contains implementations. Something like:
class Region
{
...
}
class RegionCheckManager
{
function registerCheckerForPointType(string $pointType, RegionCheckerInterface $checkerImplementation): void
{
...
}
function contains(PointInterface $point, Region $region): bool
{
return $this->getCheckerForPoint($point)->check($region, $point);
}
/** get correct checker for point type **/
private function getCheckerForPoint(PointInterface $point): RegionCheckerInterface
{
...
}
}
interface RegionCheckerInterface
{
public function contains(PointInterface $point): bool;
}
class PostcodeChecker implements RegionCheckerInterface
{
...
}
class PointChecker implements RegionCheckerInterface
{
...
}

Answer 3

Postcode and Point are different conceptual things, they are two different types. Postcode is a scalar value, Point is a geographic item. In fact, your PostalCodeRegion class is a range of scalar value, your LatLngRegion class is a geographic area that has center coordinates and radius. You try to combine two incompatible abstractions. Attempt to make one interface for two absolutely different things is the wrong way which leads to unobvious code and implicit abstractions. You should rethink your abstractions. For example:
What is a postcode? It is a positive number in the simplest case. You can create a Postcode class as a value object and implement simple methods to work with its data.
class Postcode
{
private $number;
public function __constuct(int $number)
{
assert($value <= 0, 'Postcode must be greater than 0');
$this->number = $number;
}
public function getNumber(): int
{
return $this->number;
}
public function greatOrEqual(Postalcode $value): bool
{
return $this->number >= $value->getNumber();
}
public function lessOrEqual(Postalcode $value): bool
{
return $this->number <= $value->getNumber();
}
}
What is a postcode range? It a set of postcodes that contains start postcode and end postcode. So you can also create a value object of a range and implement contains method in it.
class PostcodeRange
{
private $start;
private $end;
public function __construct(Postcode $start, Postcode $end)
{
assert(!$start->lessOrEqual($end));
$this->start = $start;
$this->end = $end;
}
public function contains(Postcode $value): bool
{
return $value->greatOrEqual($this->start) && $value->lessOrEqual($this->end);
}
}
What is a point? It is a geographic item that has some coordinates.
class Point
{
private $lan;
private $lng;
public function __constuct(float $lan, float $lng)
{
$this->lan = $lan;
$this->lng = $lng;
}
public function getLan(): float
{
return $this->lan;
}
public function getLng(): float
{
return $this->lng;
}
}
What is an area? It is a geographic region that has some borders. In your case, those borders defined with a circle that has a center point and some radius.
class Area
{
private $center;
private $radius;
public function __constuct(Point $center, int $radius)
{
$this->center = $center;
$this->radius = $radius;
}
public function contains(Point $point): bool
{
// implementation of method
}
}
So, each company has a postcode and some location defined by its coordinates.
class Company
{
private $postcode;
private $location;
public function __construct(Postcode $postcode, Point $location)
{
$this->postcode = $postcode;
$this->location = $location;
}
public function getPostcode(): Postcode
{
return $this->postcode;
}
public function getLocation(): Point
{
return $this->location;
}
}
So, how you said you have a list of companies and try to find it by postcode range or area. So you can create company collection which can contain all companies and can implement algorithms to search by necessary criteria.
class CompanyCollection
{
private $items;
public function __constuct(array $items)
{
$this->items = $items;
}
public function findByPostcodeRange(PostcodeRange $range): CompanyCollection
{
$items = array_filter($this->items, function(Company $item) use ($range) {
return $range->contains($item->getPostcode());
});
return new static($items);
}
public function findByArea(Area $area): CompanyCollection
{
$items = array_filter($this->items, function(Company $item) use ($area) {
return $area->contains($item->getLocation());
});
return new static($items);
}
}
Example of usage:
$collection = new CompanyCollection([
new Company(new Postcode(1200), new Point(1, 1)),
new Company(new Postcode(1201), new Point(2, 2)),
])
$range = new PostcodeRange(new Postcode(1000), new Postcode(2000));
$area = new Area(new Point(0, 0), 50);
// find only by postcode range
$collection->findByPostcodeRange($range);
// find only by area
$collection->findByArea($area);
// find by postcode range and area
$collection->findByPostcodeRange($range)->findByArea($area);

Answer 4

If I understand the problem correctly, you have some module M, which needs to accept some 3 objects:
implementation of region (postcodes vs radius, let's call them R1 vs R2)
implementation of point (postcode vs lat/lng, P1 vs P2)
some API C to check the point is within the region
and it then applies the 3rd object on the first 2.
(Could be that C is R1 or R2, that's immaterial for the problem definition).
So spelling out the problem: you can apply C on R1+P1 or R2+P2, but not R1+P2 or R2+P1.
I'm afraid the only way to implement it in a type-safe manner is as follows:
C is an interface, apply().
C1 implements C, and has fields of type R1, P1.
C2 implements C, and has fields of type R2, P2.
The caller builds either C1 or C2, passes it to M, and M calls c.apply().
Note how M doesn't even see points, only the checker interface C. That's because there is nothing common between P1 and P2 that anyone other than then C can use.