public class CkanClient extends Object
The client is a thin wrapper upon Ckan api, thus one method call should correspond to only one web api call. This means sometimes to get a full object from Ckan, you will need to do a second call.
You can create clients either with constructors or the
builder()
method if you need to set more
connection parameters (i.e. proxy, timeout, ..).
For writing to Ckan you might want to use CheckedCkanClient
which
does additional checks to ensure written content is correct.
Modifier and Type | Class and Description |
---|---|
static class |
CkanClient.Builder
Builder for the client.
|
(package private) static class |
CkanClient.GroupForDatasetPosting |
Modifier and Type | Field and Description |
---|---|
static String |
CKAN_NO_MILLISECS_PATTERN
Found pattern "2013-12-17T00:00:00" in resource.date_modified in
dati.toscana:
http://dati.toscana.it/api/3/action/package_show?id=alluvioni_bacreg See
also ckan issue
874 and ckan pull
2519
|
static String |
CKAN_TIMESTAMP_PATTERN
CKAN uses timestamps like '1970-01-01T01:00:00.000010' in UTC timezone,
has precision up to microsecond and doesn't append 'Z' to timestamps.
|
static int |
DEFAULT_TIMEOUT
Default timeout in millisecs
|
static String |
NONE
Sometimes we get back Python "None" as a string instead of proper JSON
null
|
static com.google.common.collect.ImmutableList<Integer> |
SUPPORTED_API_VERSIONS
Notice that even for the same api version (at least for versions up to 3
included) different CKAN instances can behave quite differently, either
for differences in software or custom server permissions.
|
Modifier | Constructor and Description |
---|---|
protected |
CkanClient() |
|
CkanClient(String catalogUrl)
Creates a Ckan client with null token
|
|
CkanClient(String catalogUrl,
String ckanToken)
Creates a Ckan client with null token
|
Modifier and Type | Method and Description |
---|---|
static CkanClient.Builder |
builder()
Returns a new client builder.
|
static void |
configureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper om)
Configures the provided Jackson ObjectMapper exactly as the internal JSON
mapper used for reading operations.
|
static void |
configureObjectMapperForPosting(com.fasterxml.jackson.databind.ObjectMapper om,
Class clazz)
Configures the provided Jackson ObjectMapper for create/update/delete
operations of Ckan objects.
|
protected org.apache.http.client.fluent.Request |
configureRequest(org.apache.http.client.fluent.Request request)
Configures the request.
|
CkanDataset |
createDataset(CkanDatasetBase dataset)
Creates CkanDataset on the server.
|
CkanGroup |
createGroup(CkanGroup group)
Creates CkanGroup on the server.
|
CkanOrganization |
createOrganization(CkanOrganization organization)
Creates CkanOrganization on the server.
|
CkanResource |
createResource(CkanResourceBase resource)
Creates ckan resource on the server.
|
CkanTag |
createTag(CkanTagBase tag)
Creates CkanTag on the server.
|
CkanUser |
createUser(CkanUserBase user)
Creates ckan user on the server.
|
CkanVocabulary |
createVocabulary(CkanVocabularyBase vocabulary)
Creates CkanVocabulary on the server.
|
void |
deleteDataset(String nameOrId)
Marks a dataset as 'deleted'.
|
void |
deleteResource(String id)
Marks a resource as 'deleted'.
|
static List<CkanPair> |
extrasMapToList(Map<String,String> map) |
static String |
formatTimestamp(Timestamp timestamp)
Formats a timestamp according to
CKAN_TIMESTAMP_PATTERN , with
precision up to microseconds. |
int |
getApiVersion()
Returns the latest api version supported by the catalog
|
String |
getCatalogUrl()
Returns the catalog URL (normalized).
|
String |
getCkanToken()
Returns the private CKAN token.
|
CkanDataset |
getDataset(String idOrName)
Fetches the dataset from ckan.
|
List<String> |
getDatasetList()
Returns list of dataset names like i.e.
|
List<String> |
getDatasetList(int limit,
int offset) |
Set<String> |
getFormats()
Returns all the resource formats available in the catalog.
|
CkanGroup |
getGroup(String idOrName)
Returns a Ckan group.
|
List<CkanGroup> |
getGroupList()
Returns the groups present in Ckan.
|
List<String> |
getGroupNames()
Return group names, like i.e.
|
List<CkanLicense> |
getLicenseList()
Returns the list of available licenses in the ckan catalog.
|
(package private) static com.fasterxml.jackson.databind.ObjectMapper |
getObjectMapper()
Retrieves the Jackson object mapper for reading operations.
|
(package private) static com.fasterxml.jackson.databind.ObjectMapper |
getObjectMapperForPosting(Class clazz)
Retrieves the Jackson object mapper configured for creation/update
operations.
|
CkanOrganization |
getOrganization(String idOrName)
Returns a Ckan organization.
|
List<CkanOrganization> |
getOrganizationList()
Returns the organizations present in CKAN.
|
List<String> |
getOrganizationNames() |
String |
getProxy()
Returns the proxy used by the client.
|
CkanResource |
getResource(String id) |
List<CkanTag> |
getTagList()
Returns a list of tags names, i.e.
|
List<String> |
getTagNamesList() |
List<String> |
getTagNamesList(String query)
Returns tags containing the string given in query.
|
int |
getTimeout()
The timeout expressed in milliseconds.
|
CkanUser |
getUser(String id) |
List<CkanUser> |
getUserList() |
static String |
makeDatasetUrl(String catalogUrl,
String datasetIdOrName)
Returns the URL of dataset page in the catalog website.
|
static String |
makeGroupUrl(String catalogUrl,
String groupNameOrId)
Given some group parameters, reconstruct the URL of group page in the
catalog website.
|
static String |
makeOrganizationUrl(String catalogUrl,
String orgNameOrId)
Given some organization parameters, reconstruct the URL of organization
page in the catalog website.
|
static String |
makeResourceUrl(String catalogUrl,
String datasetIdOrName,
String resourceId)
Returns the URL of resource page in the catalog website.
|
protected static CkanClient.Builder |
newBuilder(CkanClient client)
Convenience method to create a Builder with provided client to modify.
|
static Timestamp |
parseTimestamp(String timestamp)
Parses a Ckan timestamp into a Java Timestamp.
|
CkanDataset |
patchUpdateDataset(CkanDatasetBase dataset)
Jackan specific.
|
CkanResource |
patchUpdateResource(CkanResourceBase resource)
Jackan specific.
|
SearchResults<CkanDataset> |
searchDatasets(CkanQuery query,
int limit,
int offset)
Search datasets according to the provided query.
|
SearchResults<CkanDataset> |
searchDatasets(String text,
int limit,
int offset)
Search datasets containing provided text in the metadata
|
protected <T extends CkanResponse> |
throwCkanException(String msg,
T ckanResponse)
Throws CkanException or a subclass of it according to CkanError#getType()
|
String |
toString() |
CkanDataset |
updateDataset(CkanDatasetBase dataset)
Updates a dataset on the ckan server using a straight
package_update call. |
CkanResource |
updateResource(CkanResourceBase resource)
Updates a resource on the server using a straight
resource_update
call. |
public static final String CKAN_TIMESTAMP_PATTERN
Timestamp
or
null
if parse is not successful.parseTimestamp(java.lang.String)
,
formatTimestamp(java.sql.Timestamp)
,
Constant Field Valuespublic static final String CKAN_NO_MILLISECS_PATTERN
public static final com.google.common.collect.ImmutableList<Integer> SUPPORTED_API_VERSIONS
public static final int DEFAULT_TIMEOUT
public static final String NONE
protected CkanClient()
public CkanClient(String catalogUrl)
catalogUrl
- the catalog url i.e. http://data.gov.uk. Internally, it will
be stored in a normalized format (to avoid i.e. trailing
slashes).public CkanClient(String catalogUrl, @Nullable String ckanToken)
catalogUrl
- the catalog url i.e. http://data.gov.uk. Internally, it will
be stored in a normalized format (to avoid i.e. trailing
slashes).ckanToken
- the token used for authorization in ckan apipublic static void configureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper om)
configureObjectMapperForPosting(com.fasterxml.jackson.databind.ObjectMapper, java.lang.Class)
instead.om
- a Jackson object mapperpublic static void configureObjectMapperForPosting(com.fasterxml.jackson.databind.ObjectMapper om, Class clazz)
configureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper)
instead. For future compatibility you will need a different object mapper
for each class you want to post to ckan. DO NOT call
configureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper)
on the mapper prior to this call.om
- a Jackson object mapperclazz
- the class of the objects you wish to create/update/delete.static com.fasterxml.jackson.databind.ObjectMapper getObjectMapperForPosting(Class clazz)
clazz
- the class you want to post. For generic class, just put
Object.classstatic com.fasterxml.jackson.databind.ObjectMapper getObjectMapper()
public int getTimeout()
DEFAULT_TIMEOUT
.public static CkanClient.Builder builder()
protected org.apache.http.client.fluent.Request configureRequest(org.apache.http.client.fluent.Request request)
protected <T extends CkanResponse> void throwCkanException(String msg, T ckanResponse)
CkanException
public String getCatalogUrl()
public String getCkanToken()
public static String makeDatasetUrl(String catalogUrl, String datasetIdOrName)
datasetIdOrName
- either the dataset's alphanumerical
id
(preferred as it is more stable) or the
dataset name
catalogUrl
- i.e. http://dati.trentino.itpublic static String makeResourceUrl(String catalogUrl, String datasetIdOrName, String resourceId)
catalogUrl
- i.e. http://dati.trentino.itdatasetIdOrName
- either the dataset's alphanumerical id
(preferred as it is more stable) or the
dataset name
resourceId
- the alphanumerical id
of the
resource (DON'T use resource
name
)public static String makeGroupUrl(String catalogUrl, String groupNameOrId)
catalogUrl
- i.e. http://dati.trentino.itgroupNameOrId
- the group name as in CkanGroupOrgBase.getName()
(preferred),
or the group's alphanumerical id.public static String makeOrganizationUrl(String catalogUrl, String orgNameOrId)
catalogUrl
- i.e. http://dati.trentino.itorgNameOrId
- the group name as in CkanGroupOrgBase.getName()
(preferred), or the group's alphanumerical id.public List<String> getDatasetList()
JackanException
- on errorpublic List<String> getDatasetList(int limit, int offset)
limit
- offset
- Starts with 0 included. getDatasetList(1,0) will return
exactly one dataset, if catalog is not empty.JackanException
- on errorpublic List<CkanLicense> getLicenseList()
public int getApiVersion()
JackanException
- on errorpublic CkanDataset getDataset(String idOrName)
CkanResourceBase
idOrName
- either the dataset name (i.e. certified-products) or the
alphanumerical id (i.e. 22eea137-9fc3-4222-a716-bac22cc2039a)JackanException
- on errorpublic List<CkanUser> getUserList()
JackanException
- on errorpublic CkanUser getUser(String id)
id
- i.e. 'admin'JackanException
- on errorpublic CkanUser createUser(CkanUserBase user)
user
- ckan user object with the minimal set of parameters required.
See
this constructor
JackanException
public CkanResource getResource(String id)
id
- The alphanumerical id of the resource, such as
d0892ada-b8b9-43b6-81b9-47a86be126db.JackanException
- on errorpublic CkanResource createResource(CkanResourceBase resource)
resource
- ckan resource object with the minimal set of parameters
required. See
CkanResource.CkanResource(String, String)
JackanException
public CkanResource updateResource(CkanResourceBase resource)
resource_update
call. Null fields will not be sent and thus won't get updated, but be
careful about custom fields of CkanResourceBase.getOthers()
, if
not sent they will be erased on the server! To prevent this behaviour,
see patchUpdateResource(CkanResourceBase)
CkanException
- on errorpublic CkanResource patchUpdateResource(CkanResourceBase resource)
resource_update
call. Todo: this is a temporary solution until we
implement new patch
api of CKAN 2.3resource
- ckan resource object. Fields set to null
won't be
updated on the server. Items present in lists such as
others
will be added to
existing ones on the server. To support this behaviour
provided resource
might be patched with latest
metadata from the server prior sending it for update.CkanException
- on errorupdateResource(CkanResourceBase)
public void deleteResource(String id)
CkanState.deleted
and make it
inaccessible from the website, but you will still be able to get the
resource with the web api.id
- The alphanumerical id of the resource, such as
d0892ada-b8b9-43b6-81b9-47a86be126db.CkanException
- on errorpublic List<CkanGroup> getGroupList()
getOrganizationList()
instead.JackanException
- on errorpublic List<String> getGroupNames()
JackanException
- on errorpublic CkanGroup getGroup(String idOrName)
getOrganization(java.lang.String)
instead.idOrName
- either the group name (i.e. hospitals-in-trento-district) or
the group alphanumerical id (i.e.
55bb5fbd-7a7c-4eb8-8b1a-1192a5504421)JackanException
- on errorpublic List<CkanOrganization> getOrganizationList()
JackanException
- on errorgetGroupList()
public Set<String> getFormats()
JackanException
- on errorpublic List<String> getOrganizationNames()
JackanException
- on errorpublic CkanOrganization getOrganization(String idOrName)
idOrName
- either the name of organization (i.e. culture-and-education)
or the alphanumerical id (i.e.
232cad97-ecf2-447d-9656-63899023887f). Do not pass it a group
id.JackanException
- on errorpublic CkanTag createTag(CkanTagBase tag)
tag
- Ckan tag without idJackanException
public List<CkanTag> getTagList()
JackanException
- on errorpublic List<String> getTagNamesList(String query)
query
- JackanException
- on errorpublic List<String> getTagNamesList()
JackanException
- on errorpublic CkanVocabulary createVocabulary(CkanVocabularyBase vocabulary)
vocabulary
- Ckan vocabulary without idJackanException
public SearchResults<CkanDataset> searchDatasets(String text, int limit, int offset)
text
- The query stringlimit
- maximum results to returnoffset
- search begins from offset. Starts from 0, so that offset 0
limit 1 returns exactly 1 result, if there is a matching
dataset)JackanException
- on errorpublic static Timestamp parseTimestamp(String timestamp)
IllegalArgumentException
- if timestamp can't be parsed.for the inverse process.
@Nullable public static String formatTimestamp(Timestamp timestamp)
CKAN_TIMESTAMP_PATTERN
, with
precision up to microseconds.for the inverse process.
public SearchResults<CkanDataset> searchDatasets(CkanQuery query, int limit, int offset)
query
- The query objectlimit
- maximum results to returnoffset
- search begins from offsetCkanException
- on errorpublic CkanDataset createDataset(CkanDatasetBase dataset)
dataset
- Ckan dataset without idCkanException
public CkanDataset updateDataset(CkanDatasetBase dataset)
package_update
call. Null fields will not be sent and thus won't
get updated, but be careful about list fields, if not sent they will be
erased on the server! To prevent this behaviour, see
patchUpdateDataset(CkanDatasetBase)
CkanException
- on errorpublic CkanDataset patchUpdateDataset(CkanDatasetBase dataset)
package_update
call. Todo: this is a temporary solution until we
implement new patch
api of CKAN 2.3dataset
- ckan dataset object. Fields set to null
won't be
updated on the server. Items present in lists such as
resources
or extras
will be added to existing
ones on the server. To support this behaviour provided
dataset
might be patched with latest metadata from the
server prior sending it for update.CkanException
- on errorpublic void deleteDataset(String nameOrId)
CkanState.deleted
and make it
inaccessible from the website, but you will still be able to get the
dataset with the web api. Resources contained within will still be
'active'.nameOrId
- either the dataset name (i.e. apple-production) or the the
alphanumerical id (i.e. fe507a10-4c49-4b18-8bf6-6705198cfd42)CkanException
- on errorpublic CkanOrganization createOrganization(CkanOrganization organization)
organization
- requires at least the name or id. Only non-null fields of
CkanGroupOrgBase
will be sent to server.CkanException
- on error.public CkanGroup createGroup(CkanGroup group)
group
- requires at least the name or id. Only non-null fields of
CkanGroupOrgBase
will be sent to server.CkanException
- on error.protected static CkanClient.Builder newBuilder(CkanClient client)
WARNING: The passed client will be modified, so DO NOT pass an already built client.
The builder is not threadsafe and you can use one builder instance to build only one client instance.
Copyright © 2015 Trento Rise. All rights reserved.