forked from upstream-mirrors/OpenTracks
Rebranding to OpenTracks (code).
This commit is contained in:
Dennis Guse
@@ -0,0 +1,399 @@
|
||||
/*
|
||||
* Copyright 2010 Google Inc.
|
||||
*
|
||||
* 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 de.dennisguse.opentracks.content;
|
||||
|
||||
import android.content.Context;
|
||||
import android.database.Cursor;
|
||||
import android.location.Location;
|
||||
import android.location.LocationManager;
|
||||
import android.net.Uri;
|
||||
|
||||
import de.dennisguse.opentracks.content.Waypoint.WaypointType;
|
||||
|
||||
import java.util.Iterator;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Utilities to access data from the app's content provider.
|
||||
*
|
||||
* @author Rodrigo Damazio
|
||||
*/
|
||||
public interface ContentProviderUtils {
|
||||
|
||||
/**
|
||||
* The authority (the first part of the URI) for the app's content
|
||||
* provider.
|
||||
*/
|
||||
String AUTHORITY = "de.dennisguse.opentracks";
|
||||
/**
|
||||
* The default {@link LocationFactory} which creates a location each time.
|
||||
*/
|
||||
LocationFactory DEFAULT_LOCATION_FACTORY = new LocationFactory() {
|
||||
@Override
|
||||
public Location createLocation() {
|
||||
return new SensorDataSetLocation(LocationManager.GPS_PROVIDER);
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Clears a track. Removes waypoints and trackpoints. Only keeps the track id.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
void clearTrack(Context context, long trackId);
|
||||
|
||||
/**
|
||||
* Creates a {@link Track} from a cursor.
|
||||
*
|
||||
* @param cursor the cursor pointing to the track
|
||||
*/
|
||||
Track createTrack(Cursor cursor);
|
||||
|
||||
/**
|
||||
* Deletes all tracks (including waypoints and track points).
|
||||
*/
|
||||
void deleteAllTracks(Context context);
|
||||
|
||||
/**
|
||||
* Deletes a track.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
void deleteTrack(Context context, long trackId);
|
||||
|
||||
/**
|
||||
* Gets all the tracks. If no track exists, an empty list is returned.
|
||||
* <p>
|
||||
* Note that the returned tracks do not have any track points attached.
|
||||
*/
|
||||
List<Track> getAllTracks();
|
||||
|
||||
/**
|
||||
* Gets the last track. Returns null if doesn't exist.
|
||||
*/
|
||||
Track getLastTrack();
|
||||
|
||||
/**
|
||||
* Gets a track by a track id. Returns null if not found.
|
||||
* <p>
|
||||
* Note that the returned track doesn't have any track points attached.
|
||||
*
|
||||
* @param trackId the track id.
|
||||
*/
|
||||
Track getTrack(long trackId);
|
||||
|
||||
/**
|
||||
* Gets a track cursor. The caller owns the returned cursor and is responsible
|
||||
* for closing it.
|
||||
*
|
||||
* @param selection the selection. Can be null
|
||||
* @param selectionArgs the selection arguments. Can be null
|
||||
* @param sortOrder the sort order. Can be null
|
||||
*/
|
||||
Cursor getTrackCursor(String selection, String[] selectionArgs, String sortOrder);
|
||||
|
||||
/**
|
||||
* Inserts a track.
|
||||
* <p>
|
||||
* Note: This doesn't insert any track points.
|
||||
*
|
||||
* @param track the track
|
||||
* @return the content provider URI of the inserted track.
|
||||
*/
|
||||
Uri insertTrack(Track track);
|
||||
|
||||
/**
|
||||
* Updates a track.
|
||||
* <p>
|
||||
* Note: This doesn't update any track points.
|
||||
*
|
||||
* @param track the track
|
||||
*/
|
||||
void updateTrack(Track track);
|
||||
|
||||
/**
|
||||
* Creates a waypoint from a cursor.
|
||||
*
|
||||
* @param cursor the cursor pointing to the waypoint
|
||||
*/
|
||||
Waypoint createWaypoint(Cursor cursor);
|
||||
|
||||
/**
|
||||
* Deletes a waypoint. If deleting a statistics waypoint, this will also
|
||||
* correct the next statistics waypoint after the deleted one to reflect the
|
||||
* deletion. The generator is used to update the next statistics waypoint.
|
||||
*
|
||||
* @param waypointId the waypoint id
|
||||
* @param descriptionGenerator the description generator. Can be null for
|
||||
* waypoint marker
|
||||
*/
|
||||
void deleteWaypoint(Context context, long waypointId, DescriptionGenerator descriptionGenerator);
|
||||
|
||||
/**
|
||||
* Gets the first waypoint id for a track. The first waypoint is special as it
|
||||
* contains the stats for the track. Returns -1L if it doesn't exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
long getFirstWaypointId(long trackId);
|
||||
|
||||
/**
|
||||
* Gets the last waypoint for a type. Returns null if it doesn't exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param waypointType the waypoint type
|
||||
*/
|
||||
Waypoint getLastWaypoint(long trackId, WaypointType waypointType);
|
||||
|
||||
/**
|
||||
* Gets the next waypoint number for a type. Returns -1 if not able to get the
|
||||
* next waypoint number.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param waypointType the waypoint type
|
||||
*/
|
||||
int getNextWaypointNumber(long trackId, WaypointType waypointType);
|
||||
|
||||
/**
|
||||
* Gets a waypoint from a waypoint id. Returns null if not found.
|
||||
*
|
||||
* @param waypointId the waypoint id
|
||||
*/
|
||||
Waypoint getWaypoint(long waypointId);
|
||||
|
||||
/**
|
||||
* Gets a waypoint cursor. The caller owns the returned cursor and is
|
||||
* responsible for closing it.
|
||||
*
|
||||
* @param selection the selection. Can be null
|
||||
* @param selectionArgs the selection arguments. Can be null
|
||||
* @param sortOrder the sort order. Can be null
|
||||
* @param maxWaypoints the maximum number of waypoints to return. -1 for no
|
||||
* limit
|
||||
*/
|
||||
Cursor getWaypointCursor(String selection, String[] selectionArgs, String sortOrder, int maxWaypoints);
|
||||
|
||||
/**
|
||||
* Gets a waypoint cursor for a track. The caller owns the returned cursor and
|
||||
* is responsible for closing it.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param minWaypointId the minimum waypoint id. -1L to ignore
|
||||
* @param maxWaypoints the maximum number of waypoints to return. -1 for no
|
||||
* limit
|
||||
*/
|
||||
Cursor getWaypointCursor(long trackId, long minWaypointId, int maxWaypoints);
|
||||
|
||||
/**
|
||||
* Gets the number of waypoints for a track.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
int getWaypointCount(long trackId);
|
||||
|
||||
/**
|
||||
* Inserts a waypoint.
|
||||
*
|
||||
* @param waypoint the waypoint
|
||||
* @return the content provider URI of the inserted waypoint.
|
||||
*/
|
||||
Uri insertWaypoint(Waypoint waypoint);
|
||||
|
||||
/**
|
||||
* Updates a waypoint. Returns true if successful.
|
||||
*
|
||||
* @param waypoint the waypoint
|
||||
*/
|
||||
boolean updateWaypoint(Waypoint waypoint);
|
||||
|
||||
/**
|
||||
* Inserts multiple track points.
|
||||
*
|
||||
* @param locations an array of locations
|
||||
* @param length the number of locations (from the beginning of the array) to
|
||||
* insert, or -1 for all of them
|
||||
* @param trackId the track id
|
||||
* @return the number of points inserted
|
||||
*/
|
||||
int bulkInsertTrackPoint(Location[] locations, int length, long trackId);
|
||||
|
||||
/**
|
||||
* Creates a location object from a cursor.
|
||||
*
|
||||
* @param cursor the cursor pointing to the location
|
||||
*/
|
||||
Location createTrackPoint(Cursor cursor);
|
||||
|
||||
/**
|
||||
* Gets the first location id for a track. Returns -1L if it doesn't exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
long getFirstTrackPointId(long trackId);
|
||||
|
||||
/**
|
||||
* Gets the last location id for a track. Returns -1L if it doesn't exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
long getLastTrackPointId(long trackId);
|
||||
|
||||
/**
|
||||
* Gets the track point id of a location.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param location the location
|
||||
* @return track point id if the location is in the track. -1L otherwise.
|
||||
*/
|
||||
long getTrackPointId(long trackId, Location location);
|
||||
|
||||
/**
|
||||
* Gets the first valid location for a track. Returns null if it doesn't
|
||||
* exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
Location getFirstValidTrackPoint(long trackId);
|
||||
|
||||
/**
|
||||
* Gets the last valid location for a track. Returns null if it doesn't exist.
|
||||
*
|
||||
* @param trackId the track id
|
||||
*/
|
||||
Location getLastValidTrackPoint(long trackId);
|
||||
|
||||
/**
|
||||
* Gets the last valid location.
|
||||
*/
|
||||
Location getLastValidTrackPoint();
|
||||
|
||||
/**
|
||||
* Creates a location cursor. The caller owns the returned cursor and is
|
||||
* responsible for closing it.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param startTrackPointId the starting track point id. -1L to ignore
|
||||
* @param maxLocations maximum number of locations to return. -1 for no limit
|
||||
* @param descending true to sort the result in descending order (latest
|
||||
* location first)
|
||||
*/
|
||||
Cursor getTrackPointCursor(
|
||||
long trackId, long startTrackPointId, int maxLocations, boolean descending);
|
||||
|
||||
/**
|
||||
* Creates a new read-only iterator over a given track's points. It provides a
|
||||
* lightweight way of iterating over long tracks without failing due to the
|
||||
* underlying cursor limitations. Since it's a read-only iterator,
|
||||
* {@link Iterator#remove()} always throws
|
||||
* {@link UnsupportedOperationException}. Each call to
|
||||
* {@link LocationIterator#next()} may advance to the next DB record, and if
|
||||
* so, the iterator calls {@link LocationFactory#createLocation()} and
|
||||
* populates it with information retrieved from the record. When done with
|
||||
* iteration, {@link LocationIterator#close()} must be called.
|
||||
*
|
||||
* @param trackId the track id
|
||||
* @param startTrackPointId the starting track point id. -1L to ignore
|
||||
* @param descending true to sort the result in descending order (latest
|
||||
* location first)
|
||||
* @param locationFactory the location factory
|
||||
*/
|
||||
LocationIterator getTrackPointLocationIterator(
|
||||
long trackId, long startTrackPointId, boolean descending, LocationFactory locationFactory);
|
||||
|
||||
/**
|
||||
* Inserts a track point.
|
||||
*
|
||||
* @param location the location
|
||||
* @param trackId the track id
|
||||
* @return the content provider URI of the inserted track point
|
||||
*/
|
||||
Uri insertTrackPoint(Location location, long trackId);
|
||||
|
||||
/**
|
||||
* A lightweight wrapper around the original {@link Cursor} with a method to
|
||||
* clean up.
|
||||
*/
|
||||
interface LocationIterator extends Iterator<Location> {
|
||||
|
||||
/**
|
||||
* Gets the most recently retrieved track point id by {@link #next()}.
|
||||
*/
|
||||
long getLocationId();
|
||||
|
||||
/**
|
||||
* Closes the iterator.
|
||||
*/
|
||||
void close();
|
||||
}
|
||||
|
||||
/**
|
||||
* A factory for creating new {@link Location}.
|
||||
*/
|
||||
interface LocationFactory {
|
||||
|
||||
/**
|
||||
* Creates a new {@link Location}. An implementation can create new
|
||||
* instances or reuse existing instances for optimization.
|
||||
*/
|
||||
Location createLocation();
|
||||
}
|
||||
|
||||
/**
|
||||
* A factory which can produce instances of {@link ContentProviderUtils}, and
|
||||
* can be overridden for testing.
|
||||
*/
|
||||
class Factory {
|
||||
|
||||
private static Factory instance = new Factory();
|
||||
|
||||
/**
|
||||
* Creates an instance of {@link ContentProviderUtils}.
|
||||
*
|
||||
* @param context the context
|
||||
*/
|
||||
public static ContentProviderUtils get(Context context) {
|
||||
return instance.newForContext(context);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the factory instance.
|
||||
*/
|
||||
public static Factory getInstance() {
|
||||
return instance;
|
||||
}
|
||||
|
||||
/**
|
||||
* Overrides the factory instance for testing. Don't forget to set it back
|
||||
* to the original value after testing.
|
||||
*
|
||||
* @param factory the factory
|
||||
*/
|
||||
public static void overrideInstance(Factory factory) {
|
||||
instance = factory;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an instance of {@link ContentProviderUtils}. Allows subclasses
|
||||
* to override for testing.
|
||||
*
|
||||
* @param context the context
|
||||
*/
|
||||
protected ContentProviderUtils newForContext(Context context) {
|
||||
return new ContentProviderUtilsImpl(context.getContentResolver());
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user