|
Dark Planet Development Platform
|
|
DPS Core APIs
The DPS Core APIs are organized into a single OSGi bundle with
interfaces for the following EVE-related data:
- An API (org.dps.core.database) for retrieving static data dump objects.
- An API (org.dps.core.server) for accessing the EVE game servers.
- An API (org.dps.core.market) for managing EVE market data.
- A data model (org.dps.core.model) which defines a hierarchy for
organizing accounts, the characters included in those accounts, and
the corporations which characters are a member of.
- An API (org.dps.core.persist) for persisting state from the data
model and other core APIs. The persistence API relies
on Hibernate for access to data
which is more conveniently stored in a database (think wallet journal,
wallet transactions, industry jobs, etc).
The Core APIs provide little or no implementation. Instead,
implementations of one or more APIs are provide in separate bundles
which can be included as needed in your application. The idea is that
you only need to include implementation bundles for features you
intend to use. If you just want to write a quick utility for
retrieving account data from the EVE servers, then you only need an
implementation of the the org.dps.core.server APIs.
Factoring the system in this way makes it easy to incorporate an
exsting third party library. This is important given the large number
of third party libraries that have been written since CCP started
providing access to in-game data. Rather than re-invent the wheel,
you can wrap an existing library behind the DPS APIs. The DPS Server
API reference implementation is implemented in this way.
Each of the core APIs is accessed through the following "gateway"
interfaces:
See the API specific sections below for a detailed description of
these interfaces.
In most cases, the core APIs make use of data types which are direct
analogs of the the data types used in the EVE public APIs. For
example, prices are represented as the Java primitive
type double. Timestamps are the exception and are
represented as instances of long instead
of java.util.Date. Each such timestamp represents epoch time
in milliseconds UTC. That is, the number of milliseconds which have
elapsed since January 1, 1970 UTC. In contrast, the EVE servers
return date strings to represent timestamps. Each such string should
be converted into epoch milliseconds by the core API implementations.
The main reasons for modelling timestamps in this fashion are
simplicity and ease of manipulation. Instances
of java.util.Date carry some additional complexity such as
timezones and Java-specific modelling choices. There can also be
complications when storing native java.util.Date times in a
database because of timestamp granularity differences in different
database implementations.
In Java, it is straightforward to convert an epoch timestamp into
a java.util.Date:
long epochTime = ...stored in Core APIs...
java.util.Date asDate = new java.util.Date(epochTime);
Likewise, instances of java.util.Date can be converted to a
human friendly format with a date formatter:
java.util.Date asDate = ...epoch timestamp as date...
java.text.SimpleDateFormat dateFormatter = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss z");
String humanFriendly = dateFormatter.format(asDate);
Both of these conversions are conveniently provided in the core APIs
as part of
the IEveDataModel
interface.