As a highly extensible product, SCM-Manager offers at least three ways to interact with:
\nHaving these three layers, the error handling should be consistent among these. That is, as a developer I would not like\nto have custom made error codes in the REST layer that I cannot find in the Java API. Furthermore it is essential to get\nprecise error messages with hints how to find a way out (if possible), not only for a programmer making interactive\ncalls, but also for other programs. Last but not least it should be easy for plugin developers to adapt the error\nhandling.
\nOn the GUI layer, these information have to be translated into messages that can be easily handled.
\nHere are some example error cases:
\nUse case: Read the metadata for a branch
\nPossible errors:
\nUse case: Create a new user
\nPossible errors:
\nUse case: Update the e-mail of a repository
\nPossible errors:
\nIn SCM-Manager we make heavy use of Java Exceptions, not only for technical exceptions in the program flow like\nreading corrupt file systems, but also for \"user errors\" like illegal values or requests for missing data.
These exceptions are handled by\nJEE ExceptionMapper s. Doing so, it is\npossible to concentrate on implementing the \"happy path\" without the need to explicitly handle error cases everywhere (\nfor example you do not have to check whether got null as a result). Nonetheless we still had to decide whether to use\nchecked or unchecked exceptions. We have chosen to use unchecked exceptions due to the following reasons:
Therefore handling such an exception has to be a concious decision.
\nIn the following we will introduce the exceptions we are using:
\nNotFoundExceptionA NotFoundException is thrown, whenever \"things\" where requested but were not found.
AlreadyExistsExceptionThis exception is thrown whenever an entity cannot be created, because another entity with the same key identifyer\nexists.
\nConcurrentModificationExceptionWhen you try to modify an entity based on an outdated version, this exception is thrown. For entities like user, group\nor repository the \"last modified\" timestamp of ModelObject is used to check this.
NativeRepositoryAccessExceptionFailures while accessing native repositories (most of the time) result in java.io.IOExceptions. To distinguish these\nexceptions from other I/O errors like network exceptions and to make them unchecked, we wrap them\nin NativeRepositoryAccessException.
ResteasyViolationExceptionInput validation is handled\nusing RESTEasy's validation support.\nConstraint violations result in ResteasyViolationExceptions.
All other java.lang.RuntimeExceptions can be treated as unexpected errors, that either hint to severe problems (eg.\ndisk access failures) or implementation errors. It is unlikely that these can be handled by the program gracefully. They\nwill be caught by a generic exception handler which will wrap them in a new exception providing further SCM specific\ninformation.
Above we mentioned, that we want to use unchecked exceptions only. Therefore we have to wrap checked exceptions for\nexample created by libraries or frarmeworks to make them unchecked. Normally it is sufficiant to wrap them in a\nRuntimeException using a proper message, except you plan to handle them somewhere else than at resource level (then it\nwould be appropriate to introduce a new exception class extending RuntimeException).
Most of these exceptions must provide information about what could not have been found, updated, whatsoever. This is\nnecessary, because otherwise it may not be clear at what step of a potentionally complex process this exception occured.\nThough this sounds easy, it has some complexity because for example the access of a file in a repository can fail on\nmany levels (the file is missing in the given revision, the revision is missing, or the repository itself is missing).\nIn these cases you have to know the complete access path (what file in what revision of what changeset in what\nrepository).
\nTo ensure that this is done in a reproducable and consistent way, SCM-Manager will provide utility functions to creaate\nsuch exceptions.
\nTo be able to retrace the cause for exceptions, it is helpful to link log messages to these exceptions. To do so,\nSCM-Manager introduces transaction ids that are generated for single requests or other related actions like the\nprocessing of hooks or cron jobs. This transaction id will be part of every log message and every API response.
\nFor http requests, this can be done using MDC filter.
\nTo be able to identify different types of exceptions even outside of the java ecosystem, each SCM-Manager exception\nclass will get a unique type id that will be created using the DefaultKeyGenerator during development. We chose to\ngenerate these ids and not \"human readable\" ones to prevent collisions between plugins.
To be able to retrace errors a proper logging is indispensible. So we decided to use the following rules for logging\nexceptions:
\nINFO with their message, only. The complete stacktrace\nwill be logged at log level DEBUG.WARN with the complete stacktrace, because they indicate something\ngoing wrong on a fundamental level.SCM-Manager uses http status codes to identify types of\nerrors (and successes, that is) and doing so provides a first hint, what may have gone wrong:
\n| Status code | \nPrincipal error cause | \n
|---|---|
| 200 | \nNo error, everything is fine | \n
| 201 | \nThe item has been created without an error | \n
| 204 | \nThe request has been processed without an error | \n
| 400 | \nSomething is not valid with the data provided | \n
| 401 | \nMissing authentication (not logged in?) | \n
| 403 | \nMissing authorization | \n
| 404 | \nThe thing you are looking does not exist | \n
| 409 | \nYour update was rejected because you relate to an outdated version (maybe this item was changed in the meantime) _ | \n
| or_ the item could not be created because the key already exists | \n\n |
| 500 | \nThe \"You are not to blame\" error; something unexpected went wrong while processing the request | \n
Whenever possible, an error response contains useful details about the error in a simple json format. These information\nare not translated, so this is the responsibility of the frontend.
\n| key | \ncontent | \navailability | \n
|---|---|---|
| transactionId | \nA unique id to link your request to log messages | \nalways | \n
| errorCode | \nA code that can be used for translated error messages. To prevent the usage of the same codes in different exceptions we decided to use generated ids. | \nalways | \n
| context | \n(repo/key, branch/key, ...) | \noptional | \n
| message | \nAn english error message (not necessarily for end users) | \nalways | \n
| url | \nA URL to a site providing further information about the error | \noptional | \n
Error objects will contain no stack traces.
\nFor SCM exceptions, the message will be created from the message of the java exception. For other exceptions this will\nbe a generic message in most cases.
\nHere is an example, how a concrete exception may look like in a json response:
\n{\n \"transactionId\": \"7D82atGf3\",\n \"errorCode\": \"H823fFAt\",\n \"context\": [\n {\n \"type\": \"repository\",\n \"id\": \"scmmanager/test\"\n },\n {\n \"type\": \"branch\",\n \"id\": \"master\"\n },\n {\n \"type\": \"file\",\n \"id\": \".gitignore\"\n }\n ],\n \"message\": \"file not found\",\n \"url\": \"https://www.scm-manager.org/errors/H823fFAt\"\n}The http status code 404 is a special case, because it is a fundamental status code that can be created on a lot of\nevents:
\nSome say, that you should not try to interpret the body of a 404 response, because the origin of the response cannot be\ntaken for granted. Nonetheless we decided to use this http status code to indicate requests for missing resources,\nbecause in our view this is what most people would expect.
\nInternal errors boil down to the following message: An error occured, that could not be handled in a reasonable way by\nthe program. In these cases often only an administrator can help. Examples are out-of-memory errors, failing disk I/O,\ntimeouts accessing other services, or (to be honest) simple programming errors that have to be fixed in further\nreleases. To be able to trace these errors in the logs one can use the transaction ids.
\nAs an end user of the SCM-Manager I would not like to see confusing internals, but rather have a meaningful message in\nmy language of choice. Therefore it is necessary to identify error types on a fine level. This can be done using the\nerrorCode provided in each error object.
\nBasically we have to differentiate between errors the user can handle (\"user errors\") and technical exceptions. For user\nerrors a meaningful message can be generated giving hints to what the user has done \"wrong\". All other exceptions can be\nhandled by displaying a \"sorry, this did not work as expected\" message with the transaction id.
\nWhile creating this concepts we tried to adhere to best practices considering APIs of Twitter, Facebook, Bing, Spotify\nand others, as summarized in the following articles:
\n