From 071a624dce0be3857ea14232b7dd3f05d45f520a Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:10:00 +0200 Subject: [PATCH 1/6] docs: a new guide on overriding LyoD output --- .../advanced/manipulating-responses.md | 55 +++++++++++++++++++ mkdocs.yml | 2 + 2 files changed, 57 insertions(+) create mode 100644 docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md new file mode 100644 index 0000000..2140ffc --- /dev/null +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -0,0 +1,55 @@ +# Overriding Lyo Designer output + +Sometimes, Lyo Designer generates a code, which, in turn, produces REST responses that you would like to modify. + +Initially, you may be tempted to edit the generated code directly. However, it is best not make manual changes to the generated code. This helps prevent you changes from being overwritten by Lyo Designer the next time you re-generate the code. + +!!! tip "Reminder about code generation" + + You may be familiar with a few code generators, such as in Ruby on Rails. Those are _scaffolding_ generators, meant to help you get started. They generate code only once and let you modify it if needed. Some other generators, e.g. to generate OpenAPI clients, may be designed to be always regenerated from the definitions. Lyo Designer features an MBSE-style (model-based systems engineering) code generator that is designed to be used repeatedly and symbiotically when designing an OSLC Server. + + +Preferred options include (in the order of preference): + +1. Adjust the model definition so that Lyo Designer generates the code that suits your needs. +1. Find a code segment separated by comments `Start of user code` and `End of user` and place your code there. Such code will be preserved upon re-generation. +1. [File a bug](https://github.com/eclipse-lyo/lyo.designer/issues/new?template=BLANK_ISSUE) on Lyo Designer and request a new user code block to be added where you need it. +1. Consider using an interceptor below. +1. Resort to making changes to the generated code. + + +## Defining an interceptor + +A sample interceptor below adds an extra `jfs:oauthRealmName` property to all responses featuring an OSLC Service Provider Catalog. + +```java +import javax.ws.rs.ext.WriterInterceptor; +import javax.ws.rs.ext.WriterInterceptorContext; +import javax.xml.namespace.QName; + +@Provider +public class ExtendedPropWriteInterceptor implements WriterInterceptor { + private static final QName OAUTH_REALM_NAME = new QName("http://jazz.net/xmlns/prod/jazz/jfs/1.0/", "oauthRealmName"); + private final Logger log = LoggerFactory.getLogger(ExtendedPropWriteInterceptor.class); + + @Override + public void aroundWriteTo(WriterInterceptorContext context) throws IOException, WebApplicationException { + log.info("Interceptor called"); + final Object entity = context.getEntity(); + if (entity instanceof ServiceProviderCatalog) { + final ServiceProviderCatalog catalog = (ServiceProviderCatalog) entity; + catalog.getExtendedProperties().put(OAUTH_REALM_NAME, AuthenticationApplication.OAUTH_REALM); + context.setEntity(catalog); + } + context.proceed(); + } +} +``` + + +!!! tip + Do not forget to register the interceptor in the `Application.java` + + ```java + RESOURCE_CLASSES.add(ExtendedPropWriteInterceptor.class); + ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 0904dbc..22fa044 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -192,6 +192,8 @@ nav: - Modelling How-To: eclipse_lyo/modelling-howto.md - Domain Specification workshop: eclipse_lyo/domain-specification-modelling-workshop.md - Toolchain Modelling workshop: eclipse_lyo/toolchain-modelling-workshop.md + - Advanced topics: + - Overriding Lyo Designer output: eclipse_lyo/designer/advanced/manipulating-responses.md - OSLC4JS: oslc-open-source-node-projects.md - OSLC4Net: https://oslc4net.github.io/ - PyOSLC: https://github.com/cslab/pyoslc From c532830d1110daba21c33bf4fa702b93e026b7cb Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:11:35 +0200 Subject: [PATCH 2/6] reword --- .../eclipse_lyo/designer/advanced/manipulating-responses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md index 2140ffc..7f5fd1c 100644 --- a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -6,7 +6,7 @@ Initially, you may be tempted to edit the generated code directly. However, it i !!! tip "Reminder about code generation" - You may be familiar with a few code generators, such as in Ruby on Rails. Those are _scaffolding_ generators, meant to help you get started. They generate code only once and let you modify it if needed. Some other generators, e.g. to generate OpenAPI clients, may be designed to be always regenerated from the definitions. Lyo Designer features an MBSE-style (model-based systems engineering) code generator that is designed to be used repeatedly and symbiotically when designing an OSLC Server. + You may be familiar with a few code generators, such as in Ruby on Rails. Those are _scaffolding_ generators, meant to help you get started. They generate code only once and encourage you modify it further. Some other generators, e.g. to generate OpenAPI clients, may be designed to be always regenerated from the definitions. Lyo Designer features an MBSE-style (model-based systems engineering) code generator that is designed to be used repeatedly and symbiotically when designing an OSLC Server. Preferred options include (in the order of preference): From e856f3f133fa4f56cddfcf565744e00eff7cf46a Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:14:13 +0200 Subject: [PATCH 3/6] docs: extra suggestion --- docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md index 7f5fd1c..a35a887 100644 --- a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -14,6 +14,7 @@ Preferred options include (in the order of preference): 1. Adjust the model definition so that Lyo Designer generates the code that suits your needs. 1. Find a code segment separated by comments `Start of user code` and `End of user` and place your code there. Such code will be preserved upon re-generation. 1. [File a bug](https://github.com/eclipse-lyo/lyo.designer/issues/new?template=BLANK_ISSUE) on Lyo Designer and request a new user code block to be added where you need it. +1. Consider changes to the dependency injection in the `ApplicationBinder` to use your implementations where necessary. 1. Consider using an interceptor below. 1. Resort to making changes to the generated code. From e6cda34aa1ecd3b2efb37104015a33d1f2b3a48e Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:25:12 +0200 Subject: [PATCH 4/6] Update docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../eclipse_lyo/designer/advanced/manipulating-responses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md index a35a887..7ddc438 100644 --- a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -1,6 +1,6 @@ # Overriding Lyo Designer output -Sometimes, Lyo Designer generates a code, which, in turn, produces REST responses that you would like to modify. +Sometimes, Lyo Designer generates code, which, in turn, produces REST responses that you would like to modify. Initially, you may be tempted to edit the generated code directly. However, it is best not make manual changes to the generated code. This helps prevent you changes from being overwritten by Lyo Designer the next time you re-generate the code. From a73bc344cd242d86fdea8598d36b8723b4a4ed7b Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:25:20 +0200 Subject: [PATCH 5/6] Update docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../eclipse_lyo/designer/advanced/manipulating-responses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md index 7ddc438..17c8225 100644 --- a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -2,7 +2,7 @@ Sometimes, Lyo Designer generates code, which, in turn, produces REST responses that you would like to modify. -Initially, you may be tempted to edit the generated code directly. However, it is best not make manual changes to the generated code. This helps prevent you changes from being overwritten by Lyo Designer the next time you re-generate the code. +Initially, you may be tempted to edit the generated code directly. However, it is best not to make manual changes to the generated code. This helps prevent you changes from being overwritten by Lyo Designer the next time you re-generate the code. !!! tip "Reminder about code generation" From 3a0cc0eb40195001f7408a7501e10f8d73df896c Mon Sep 17 00:00:00 2001 From: Andrew Berezovskyi Date: Sat, 12 Jul 2025 17:25:32 +0200 Subject: [PATCH 6/6] Update docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../eclipse_lyo/designer/advanced/manipulating-responses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md index 17c8225..3247fd7 100644 --- a/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md +++ b/docs-new/eclipse_lyo/designer/advanced/manipulating-responses.md @@ -12,7 +12,7 @@ Initially, you may be tempted to edit the generated code directly. However, it i Preferred options include (in the order of preference): 1. Adjust the model definition so that Lyo Designer generates the code that suits your needs. -1. Find a code segment separated by comments `Start of user code` and `End of user` and place your code there. Such code will be preserved upon re-generation. +1. Find a code segment separated by comments `Start of user code` and `End of user code` and place your code there. Such code will be preserved upon re-generation. 1. [File a bug](https://github.com/eclipse-lyo/lyo.designer/issues/new?template=BLANK_ISSUE) on Lyo Designer and request a new user code block to be added where you need it. 1. Consider changes to the dependency injection in the `ApplicationBinder` to use your implementations where necessary. 1. Consider using an interceptor below.