Um die Anbindung eigener Anwendungen an den URN-Service bzw. die URN-Rest-API zu unterstützen, bieten stellen wir einen Java-Client zur Verfügung.
Die Nutzung des Java-Clients erfolgt auf eigene Gefahr. Anpassungen finden nur innerhalb unseres URN-Releases-Prozess statt.
Folgende Schnittstellen
| UrnNamespaceRepository | Interface for using the query- and creation-methods related to URN-Namespaces. |
| UrnOrganisationRepository | Interface for using the query-methods related to URN-Organisations. |
| UrnPoliciesRepository | Interface for using the query-methods related to URN-Policies. |
| UrnRepository | Interface for REST-API-Entry-Point to get information via RESTApiInfoResource about the URN-REST-API itself. |
| UrnUrnRepository | Interface for using the query- and creation-methods related to URNs. |
wurden hier implementiert:
| UrnNamespaceRestClient | Entry point for the users of the URN client to access the RESTNamespaceResources. |
| UrnOrganisationRestClient | Entry point for the users of the URN client to access the RESTOrganisationResource. |
| UrnPoliciesRestClient | Entry point for the users of the URN client to access the RESTPoliciesResource. |
| UrnRestClient | Entry point for the users of the URN client to get information via RESTApiInfoResource about the URn-REST-API. |
| UrnUrnRestClient | Handles the task of making the connections and the requests to the Urn-Service's RestApi. |
Schritt-für-Schritt-Anleitung
Technische Voraussetzungen:
- Die Verwendung von Java 8 oder kompatiblere JVM Sprache in der entsprechenden Version.
- Berechtigung zur Einspielung von URNS der eigenen Institutionen innerhalb des eigenen Namensraumes in Form von LOGIN / USER Credentials.
- Die URL zur URN-Rest-API (z.B.: "http://api.nbn-resolving.org/sandbox/v2/").
...
Implementierungen
| Anker | ||||
|---|---|---|---|---|
|
| Codeblock | ||||
|---|---|---|---|---|
| ||||
private static final String V2_URI = "httphttps://apisandbox.nbn-resolving.org/sandbox/v2/"; private static UrnRestClient urnRepository; public static void main(String[] args) { urnRepository = new UrnRestClient(V2_URI); final ApiInfo info = urnRepository.getInfo(); } |
...
| Info | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
ApiInfo [ self=httphttps://apisandbox.nbn-resolving.org/sandbox/v2/, ] |
...
| Anker | ||||
|---|---|---|---|---|
|
Um die Namensräume gezielt abfragen zu können, werden Filter- und Sortierparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
...
Suche über alle Namensräume
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "httphttps://apisandbox.nbn-resolving.org/sandbox/v2/"; private static final String DEFAULT_NASP_WILDCARD = "urn:nbn:de*"; private static UrnNamespaceRestClient naspRepository; public static void main(String[] args) { naspRepository = new UrnNamespaceRestClient(V2_URI); final Optional<NamespaceFilter> naspFilter = Optional .of(new NamespaceFilter(NamespaceFilterKey.NAME, DEFAULT_NASP_WILDCARD)); final NamespaceSortParameters naspsortparams = new NamespaceSortParameters().getDefault(); naspsortparams.setSortBy(NamespaceSortKey.NAME); final PagingParameters pagingParameters = new PagingParameters().getDefault(); UrnRestResultNamespaceObject result = null; try { result = naspRepository.getNamespacesWithFilter(ORG_LOGIN, ORG_PASSWORD, naspFilter, naspsortparams, pagingParameters); } catch (final UrnRestApiNotAvailableException e) { System.out.println("The client cannot connect to the URN-REST-API."); } } |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - You will only see information enabled for your login. .... .... .... |
...
Suche nach einem bestimmten Namensraum mittels Namen
Führt eine Suche nach einem bestimmten Namensraum durch.
...
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "httphttps://apisandbox.nbn-resolving.org/sandbox/v2/"; private static final String DEFAULT_NASP_WILDCARD = "urn:nbn:de*"; private static final String ORG_NAMESPACE = "urn:nbn:de:0007"; private static UrnNamespaceRestClient naspRepository; public static void main(String[] args) { naspRepository = new UrnNamespaceRestClient(V2_URI); UrnRestResultNamespaceObject result = null; try { result = naspRepository.getNamespaceViaName(ORG_LOGIN, ORG_PASSWORD, ORG_NAMESPACE, ORG_USER); } catch (final UrnRestApiNotAvailableException e) { System.out.println("The client cannot connect to the URN-REST-API."); } LOGGER.info("Response End..."); } |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getNamespace()... |
UrnOrganisationClient
...
| Anker | ||||
|---|---|---|---|---|
|
Suche nach bestimmter Organisation mittels Login-Name
Führt eine Suche nach einer bestimmten Organisation durch.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Identifier Login-Name der zu suchenden Organisation. Der letzte Parameter ist nur für Admins relevant (runAs) und kann leer bleiben.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static UrnOrganisationRestClient orgRepository;
public static void main(String[] args) {
orgRepository = new UrnOrganisationRestClient(V2_URI);
UrnRestResultOrganisationObject resultObject = null;
try {
resultObject = orgRepository.getOrganisationByLogin(ORG_USER, ORG_PASSW, ORG_USER, ORG_USER);
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getOrganisationByID()... |
...
Suche nach bestimmter Organisation mittels Organisations-Identifier
Funktioniert analog zum vorherigen Beispiel.
...
Suche über alle Organisationen mittels Filter
Um die Organisationen gezielt abfragen zu können, werden Filter- und Sortierparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static UrnOrganisationRepository orgRepository;
public static void main(String[] args) {
orgRepository = new UrnOrganisationRestClient(V2_URI);
final Optional<OrganisationFilter> orgFilter = Optional
.of(new OrganisationFilter(OrganisationFilterKey.NAME, "Test*"));
UrnRestResultOrganisationObject resultObject = null;
try {
resultObject = orgRepository.getOrganisationsWithParams(ORG_LOGIN , ORG_PASSWORD , orgFilter,
new OrganisationSortParameters(), new PagingParameters());
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getOrganisationWithFilter()... [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - Response End... |
| Anker | ||||
|---|---|---|---|---|
|
...
Suche über alle URNs mittels Filter
Führt eine Suche nach einer bestimmten Organisation URNs durch.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Identifier der zu suchenden Organisation. Der letzte Parameter ist nur für Admins relevant (runAs) und kann leer bleiben.
Um die Organisationen gezielt URNs gezielter abfragen zu können, werden Filter-, Sortier-, und Paginierungsparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String DEFAULT_URN_WILDCARD = "urn:nbn:de:01*";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
urnUrnRepository = new UrnUrnRestClient(V2_URI);
final Optional<UrnFilter> urnFilter = Optional.of(new UrnFilter(UrnFilterKey.URN, DEFAULT_URN_WILDCARD));
final UrnSortParameters urnsortparams = new UrnSortParameters().getDefault();
final PagingParameters pagingParameters = new PagingParameters().getDefault();
UrnRestResultUrnObject result = null;
try {
result = urnUrnRepository.getUrnsWithParams(ORG_LOGIN, ORG_PASSWORD, urnFilter, urnsortparams,
pagingParameters);
logUrnRestResultUrnObjectToString(result);
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getUrns()... [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - Response End... |
...
Lieferung von Vorschlägen für URN-Namen
Ein berechtigter Nutzer lässt sich URN-Namen für den eigenen Namensraum vorschlagen.
...
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static UrnNamespaceRestClient naspRepository;
public static void main(String[] args) {
naspRepository = new UrnNamespaceRestClient(V2_URI);
UrnRestResultNamespaceObject suggestResult;
try {
suggestResult = naspRepository.suggestUrnName(ORG_USER, ORG_PASSW, ORG_NAMESPACE, "2");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getUrnSuggestions()... |
...
Hinzufügen einer neuen URN
Ein berechtigter Nutzer fügt dem URN-System eine neue URN samt URLs hinzu.
...
Zusätzlich muss ein RESTCreateUrnRequest zusammengebaut werden, der wiederum einzelne RESTCreateUrlRequests beinhaltet.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/"; private static final String ORG_ID = "19066"; private static UrnUrnRestClient urnUrnRepository; public static void main(String[] args) { URI uriEins = null; URI orgaId = null; URI uriZwei = null; String urnString = "urn:nbn:de:0007-2307251255492.453473381209"; try { uriEins = new URI("https://test/forUrnClient_1.pdf"); uriZwei = new URI("https://test/fforUrnClient_2.docx"); orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID); } catch (final URISyntaxException e) { System.out.println("URI Syntax not conform to RFC."); } final List<de.dnb.resolvingdienste.urnadministration.urn.restapi.model.RESTCreateUrlRequest> requestsListUrls = new ArrayList<RESTCreateUrlRequest>(); UrnRestResultUrnObject response = null; requestsListUrls.add(RESTCreateUrlRequestWithDefaultsBuilder.aRESTCreateUrlRequest().withOrganisation(orgaId) .withUrl(uriEins).build()); requestsListUrls.add(RESTCreateUrlRequestWithDefaultsBuilder.aRESTCreateUrlRequest().withOrganisation(orgaId) .withUrl(uriZwei).build()); final de.dnb.resolvingdienste.urnadministration.urn.restapi.model.RESTCreateUrnRequest createRequest = RESTCreateUrnRequestWithDefaultsBuilder .aRESTCreateUrnRequest() .withUrn(urnString).withUrls(requestsListUrls).build(); try { response = urnUrnRepository.addNewUrn(ORG_USER, ORG_PASSW, createRequest, ORG_USER); } catch (final UrnRestApiNotAvailableException e1) { System.out.println("The client cannot connect to the URN-REST-API."); } } |
...
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - addUrn()... |
Hinzufügen einer neuen URL zu bestehender URN
Ein berechtigter Nutzer fügt einer URN eine neue URL hinzu.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Name der URN und der RESTCreateUrlRequest. Der letzte Parameter (runAs) ist nur für Admins relevant und kann leer bleiben.
Zusätzlich muss ein RESTCreateUrlRequests zusammengebaut werden.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static final String URN_NAME = "urn:nbn:de:0007-2307251300155.775903492814";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
URI urineu = null;
URI orgaId = null;
try {
urineu = new URI("https://testUri/forClient_3".pdf");
orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID);
} catch (final URISyntaxException e) {
System.out.println("URI Syntax not conform to RFC.");
}
final RESTCreateUrlRequest createUrlRequest = new RESTCreateUrlRequest();
createUrlRequest.setUrl(urineu);
createUrlRequest.setOwner(orgaId);
UrnRestResultUrlObject restCallresponse = null;
try {
restCallresponse = urnUrnRepository.addNewUrl(ORG_USER, ORG_PASSW, URN_NAME , createUrlRequest, "");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultUrnObject. Das UrnRestResultUrnObject "wrapt" die ursprünglichen RESTUrlRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...). In diesem besonderen Fall wird lediglich das RESTUrlRepresentation-Objekt in das UrnRestResultUrnObject gehängt und man bekommt die Info, ob der Request erfolgreich war.
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - UrnRestResultUrlObject [ |
Updates aller URLs einer URN
Ein berechtigter Nutzer tauscht die eigenen URLs einer bestimmten URN aus.
urnUrnRepository.updateUrl(ORG_LOGIN, ORG_PASSWORD, URN_NAME , allMyUrls, "");Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Name der URN und der RESTCreateUrlRequest (allMyUrls). Der letzte Parameter (runAs) ist nur für Admins relevant und kann leer bleiben.
Der RESTCreateUrlRequests muss selbst zusammengebaut werden.
WICHTIG: Alle eigenen URLs, die vor diesem Request zur URN gehört haben und NICHT mehr in diesem Request aufgeführt werden, werden gelöscht. Das gilt nicht für fremde URLs anderer Institutionen.
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static final String URN_NAME = "urn:nbn:de:0007-2307251300155.775903492814";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
URI uriEins = null;
URI orgaId = null;
URI uriZwei = null;
try {
uriEins = new URI("https://testUri/forClient/repl_1".pdf");
uriZwei = new URI("https://testUri/forClient/repl_2".docx");
orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID);
} catch (final URISyntaxException e) {
System.out.println("URI Syntax not conform to RFC.");
}
final List<RESTReplaceUrlRequest> allMyUrls = new ArrayList<RESTReplaceUrlRequest>();
final RESTReplaceUrlRequest eins = new RESTReplaceUrlRequest();
eins.setUrl(uriZwei);
eins.setPriority(1);
final RESTReplaceUrlRequest zwei = new RESTReplaceUrlRequest();
zwei.setUrl(uriDrei);
zwei.setPriority(0);
allMyUrls.add(eins);
allMyUrls.add(zwei);
UrnRestResultObject restCallresponse = null;
try {
restCallresponse = urnUrnRepository.updateUrl(ORG_LOGIN, ORG_PASSWORD, URN_NAME , allMyUrls,
"");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultObject. In diesem besonderen Fall werden lediglich Information darüber zurückgegeben, ob der Request erfolgreich war.
| Info | ||
|---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - You will only see information enabled for your login. |